@webda/graphql 4.0.0-beta.2 → 4.0.0-beta.3

package/README.md

@@ -1,14 +1,136 @@
-# @webda/graphql
+# @webda/graphql module
 
-Implements the GraphQL protocol with subscriptions and mutations
+This module is part of Webda Application Framework that allows you to quickly develop applications with all modern prerequisites: Security, Extensibility, GraphQL, REST, CloudNative [https://webda.io](https://webda.io)
 
+<img src="https://webda.io/images/webda.svg" width="128" />
+
+![CI](https://github.com/loopingz/webda.io/workflows/CI/badge.svg)
+
+[![Join the chat at https://gitter.im/loopingz/webda](https://badges.gitter.im/loopingz/webda.svg)](https://gitter.im/loopingz/webda?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![codecov](https://codecov.io/gh/loopingz/webda.io/branch/main/graph/badge.svg?token=8N9DNM3K3O)](https://codecov.io/gh/loopingz/webda.io)
+[![SonarCloud.io](https://sonarcloud.io/api/project_badges/measure?project=loopingz_webda.io&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=loopingz_webda.io)
+![CodeQL](https://github.com/loopingz/webda.io/workflows/CodeQL/badge.svg)
+
+<!-- README_HEADER -->
+
+## @webda/graphql
+
+Auto-generates a fully functional GraphQL API — queries, mutations, **and subscriptions** — from your Webda domain models. Zero hand-written SDL required.
+
+### When to use it
+
+Add `@webda/graphql` when you want a GraphQL endpoint alongside (or instead of) the REST endpoint. It reads your model graph from `@webda/compiler`'s model manifest and builds the GraphQL schema dynamically. Subscriptions over WebSocket (`graphql-ws`) are enabled by default.
+
+### Install
+
+```bash
+npm install @webda/graphql
 ```
-// Add a ping to subscription (useful for testing)
-setInterval(() => this.emit("Ping", Date.now()), this.parameters.pingInterval);
-subscriptions["Ping"] = {
-    type: GraphQLLong,
-    subscribe: async (source, args, context: any, info: GraphQLResolveInfo) => {
-    return new EventIterator(this, "Ping", "Ping", Date.now()).iterate();
+
+### Configuration
+
+Add the `GraphQLService` to your `webda.config.json`:
+
+```json
+{
+  "services": {
+    "GraphQLService": {
+      "type": "Webda/GraphQLService",
+      "url": "/graphql",
+      "exposeGraphiQL": true,
+      "globalSubscription": true
     }
-};
+  }
+}
+```
+
+### Auto-generated operations
+
+For every exposed model (e.g. `Post`) the service generates:
+
+| Operation | Type | Description |
+|-----------|------|-------------|
+| `Post(uuid)` | Query | Fetch one by primary key |
+| `Posts(query, limit, offset)` | Query | List / filter all |
+| `createPost(Post: PostInput)` | Mutation | Create new instance |
+| `updatePost(uuid, Post: PostInput)` | Mutation | Replace by primary key |
+| `deletePost(uuid)` | Mutation | Delete by primary key |
+| `PostEvents` | Subscription | Stream events for all posts |
+| `PostEvent(uuid)` | Subscription | Stream events for a specific post |
+
+Custom `@Operation()` methods on the model become additional mutations or queries automatically.
+
+### Quick usage
+
+```graphql
+# Query all published posts
+{ Posts { results { slug title status viewCount } } }
+
+# Create a post
+mutation {
+  createPost(Post: {
+    title: "Hello World"
+    slug: "hello-world"
+    content: "My first post content with enough text."
+    status: "draft"
+    viewCount: 0
+  }) {
+    slug
+    title
+  }
+}
 ```
+
+### Subscriptions (graphql-ws)
+
+```graphql
+subscription {
+  PostEvents {
+    Created { object { slug title } }
+    Updated { object { slug title } }
+    Deleted { object_id }
+  }
+}
+```
+
+The subscription server uses `graphql-ws` over WebSocket (same port as the HTTP server when TLS is enabled via `autoTls`).
+
+### GraphiQL
+
+Set `exposeGraphiQL: true` (the default) to enable the in-browser GraphiQL IDE at `/graphql`. Useful for development and introspection.
+
+### Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `url` | `/graphql` | HTTP endpoint path |
+| `exposeGraphiQL` | `true` | Serve the GraphiQL explorer UI |
+| `exposeMe` | `true` | Expose `{ me { ... } }` query for current user |
+| `globalSubscription` | `true` | Expose aggregate `AggregateSubscriptions` subscription |
+| `userModel` | `User` | Short name of the User model for `me` query |
+
+### See also
+
+- [Schema Generation](../../docs/pages/Modules/graphql/Schema-Generation.md)
+- [Queries and Mutations](../../docs/pages/Modules/graphql/Queries-And-Mutations.md)
+- [Subscriptions](../../docs/pages/Modules/graphql/Subscriptions.md)
+- [@webda/core DomainService](../core/README.md) — base class for model-serving services
+
+<!-- README_FOOTER -->
+## Sponsors
+
+<!--
+Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor](mailto:sponsor@webda.io)
+-->
+
+Arize AI is a machine learning observability and model monitoring platform. It helps you visualize, monitor, and explain your machine learning models. [Learn more](https://arize.com)
+
+[<img src="https://arize.com/hubfs/arize/brand/arize-logomark-1.png" width="200">](https://arize.com)
+
+Loopingz is a software development company that provides consulting and development services. [Learn more](https://loopingz.com)
+
+[<img src="https://loopingz.com/images/logo.png" width="200">](https://loopingz.com)
+
+Tellae is an innovative consulting firm specialized in cities transportation issues. We provide our clients, both public and private, with solutions to support your strategic and operational decisions. [Learn more](https://tellae.fr)
+
+[<img src="https://tellae.fr/" width="200">](https://tellae.fr)

package/lib/graphql.service.d.ts

@@ -0,0 +1,205 @@
+import { Application, DomainService, DomainServiceParameters, ModelDefinition, WebContext } from "@webda/core";
+import type { ModelGraph } from "@webda/compiler";
+import * as WebdaQL from "@webda/ql";
+import { FieldNode, GraphQLFieldConfig, GraphQLObjectType, GraphQLResolveInfo, GraphQLSchema, GraphQLType, ThunkObjMap } from "graphql";
+import { Handler } from "graphql-http";
+import { Server as GraphQLWSServer } from "graphql-ws";
+import { JSONSchema7 } from "json-schema";
+import { WebSocketServer } from "ws";
+export interface GraphQLContextExtension {
+    /**
+     * Get the current count of operation for this request
+     */
+    count?: number;
+}
+/**
+ * Parameters for the GraphQL service
+ */
+export declare class GraphQLParameters extends DomainServiceParameters {
+    /**
+     * URL for the GraphQL endpoint
+     * @default /graphql
+     */
+    url: string;
+    /**
+     * Max number of requests allowed within a graphql query or mutation
+     *
+     * @default 10
+     */
+    maxOperationsPerRequest: number;
+    /**
+     * User model to expose
+     * @default User
+     */
+    userModel: string;
+    /**
+     * Expose current user in the context with me
+     * @default true
+     */
+    exposeMe: boolean;
+    /**
+     * Expose the schema
+     */
+    exposeGraphiQL: boolean;
+    /**
+     * Expose a aggregation of all available subscriptions
+     */
+    globalSubscription: boolean;
+    /**
+     * Load parameters with defaults
+     * @param params - raw configuration values
+     * @returns this for chaining
+     */
+    load(params?: any): this;
+}
+/**
+ * Implement a GraphQL service
+ *
+ * It will expose all your exposed models as GraphQL types
+ * Dynamically generate the schema
+ *
+ * @WebdaModda
+ */
+export declare class GraphQLService<T extends GraphQLParameters = GraphQLParameters> extends DomainService<T> {
+    schema: GraphQLSchema;
+    handler: Handler;
+    modelsMap: {
+        [key: string]: GraphQLObjectType;
+    };
+    app: Application;
+    wss: WebSocketServer;
+    wsHandler: GraphQLWSServer;
+    modelListeners: any;
+    /**
+     * Load and initialize GraphQL service parameters
+     * @param params - raw partial configuration
+     * @returns initialized GraphQLParameters
+     */
+    loadParameters(params: any): GraphQLParameters;
+    /**
+     * Resolve a JSON Schema property by following $ref pointers
+     * @param prop - JSON Schema property that may contain $ref
+     * @param definitions - schema definitions map for resolving references
+     * @returns the resolved JSON Schema (or a null type if unresolvable)
+     */
+    getJsonSchemaDefinition(prop: JSONSchema7, definitions?: {}): JSONSchema7;
+    /**
+     * Convert a JSON Schema to a GraphQL type definition
+     * @param schema - JSON Schema to convert
+     * @param defaultName - fallback name for anonymous types
+     * @param input - if true, generate GraphQLInputObjectType instead of GraphQLObjectType
+     * @returns object with the GraphQL type and optional description, or undefined for null types
+     */
+    getGraphQLSchemaFromSchema(schema: JSONSchema7, defaultName: string, input?: boolean): {
+        type: GraphQLType;
+        description?: string;
+    };
+    /**
+     * Get or create a GraphQL query result wrapper type with results array and continuationToken
+     * @param type - GraphQL object type to wrap in a query result
+     * @returns GraphQL object type with results and continuationToken fields
+     */
+    getGraphQLQueryResult(type: any): GraphQLObjectType<any, any>;
+    /**
+     * Build GraphQL field definitions from a JSON Schema, enriching with relation resolvers from the model graph
+     * @param schema - JSON Schema describing the model properties
+     * @param defaultName - fallback name for generated types
+     * @param webdaGraph - model relation graph (links, maps, queries, parent)
+     * @param input - if true, generate input types (skip readonly fields, skip relation resolvers)
+     * @returns map of field names to GraphQL field configs
+     */
+    getGraphQLFieldsFromSchema(schema: JSONSchema7, defaultName: string, webdaGraph?: ModelGraph, input?: boolean): any;
+    /**
+     * Load a model instance, optimizing to skip store reads when all requested fields are already known
+     * @param knownFieldsOrId - UUID string or object with known field values
+     * @param model - model class to load from
+     * @param context - web context for permission checks
+     * @param info - GraphQL field node describing the selection set
+     * @param filter - optional WebdaQL filter to apply to the result
+     * @returns the model instance, or null if filtered out
+     */
+    loadModelInstance(knownFieldsOrId: string | {
+        uuid: string;
+        [key: string]: any;
+    }, model: ModelDefinition<any>, context: WebContext, info?: FieldNode, filter?: WebdaQL.PartialValidator): Promise<any>;
+    /**
+     * Increment the operation counter and throw if the per-request limit is exceeded
+     * @param context - web context holding the graphql extension with the counter
+     * @param increment - number of operations to add (default 1)
+     */
+    countOperation(context: WebContext, increment?: number): void;
+    /**
+     * Set up WebSocket server for GraphQL subscriptions and register upgrade handler
+     * @returns this instance for chaining
+     */
+    resolve(): this;
+    /**
+     * Generate GraphQL schema
+     */
+    generateSchema(): void;
+    /**
+     * Extract the list of event names from the GraphQL selection set (excluding latestEventTime)
+     * @param info - GraphQL resolve info containing field selections
+     * @returns array of event name strings the client subscribed to
+     */
+    getSubscribedEvents(info: GraphQLResolveInfo): string[];
+    /**
+     * Create an async iterator that streams query results, updating when store events occur
+     * @param model - model class to query
+     * @param plural - plural name used as the iterator prefix key
+     * @param query - WebdaQL query string
+     * @param context - web context for permission checks
+     * @returns async iterator yielding updated query results on store changes
+     */
+    registerAsyncIteratorQuery(model: ModelDefinition<any>, plural: string, query: string, context: any): Promise<AsyncIterator<any>>;
+    /**
+     * Create an async iterator that streams a single model instance, updating on store events
+     * @param model - model class the instance belongs to
+     * @param uuid - UUID of the specific instance to watch
+     * @param context - web context for permission checks
+     * @param identifier - optional key used as the iterator prefix (defaults to model identifier)
+     * @returns async iterator yielding the updated model on each store change
+     */
+    registerAsyncIterator(model: ModelDefinition<any>, uuid: any, context: any, identifier?: string): Promise<AsyncIterator<any>>;
+    /**
+     * Create an async iterator for raw model events (not full objects), filtered by event name and UUID
+     * @param model - model class to listen on
+     * @param uuid - UUID to filter events for, or null for all instances
+     * @param events - list of event names the client wants to receive
+     * @param context - web context for authorization checks
+     * @param identifier - key used as the iterator prefix
+     * @returns async iterator yielding event payloads with latestEventTime
+     */
+    registerAsyncEventIterator(model: ModelDefinition<any>, uuid: string | null, events: string[], context: any, identifier: string): Promise<AsyncIterator<any>>;
+    /**
+     * Assemble the final GraphQLSchema from root query fields, mutations, and subscriptions
+     * @param rootFields - top-level query fields
+     * @param mutations - mutation fields
+     * @param subscription - subscription fields
+     * @returns the constructed GraphQLSchema
+     */
+    getGraphQLSchema(rootFields: ThunkObjMap<GraphQLFieldConfig<any, any, any>>, mutations?: ThunkObjMap<GraphQLFieldConfig<any, any, any>>, subscription?: ThunkObjMap<GraphQLFieldConfig<any, any, any>>): GraphQLSchema;
+    /**
+     * @override
+     */
+    init(): Promise<this>;
+    /**
+     * Check whether a model should be handled by this service (always returns true)
+     * @param model - model class to check
+     * @param name - display name of the model
+     * @param context - request context
+     * @returns true if the model should be processed
+     */
+    handleModel(model: ModelDefinition<any>, name: string, context: any): boolean;
+    /**
+     * Serve the GraphQL schema as text or the GraphiQL IDE as HTML
+     * @param ctx - incoming web context
+     */
+    schemaRoute(ctx: WebContext<any>): Promise<void>;
+    /**
+     * Handle POST requests to the GraphQL endpoint
+     * @param ctx - incoming web context with the GraphQL query body
+     */
+    endpoint(ctx: WebContext<any>): Promise<void>;
+}
+//# sourceMappingURL=graphql.service.d.ts.map

package/lib/graphql.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql.service.d.ts","sourceRoot":"","sources":["../src/graphql.service.ts"],"names":[],"mappings":"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"}