@znight/graphql 0.0.0 → 0.2.1

package/dist/types-DQ713UgI.d.mts

@@ -0,0 +1,266 @@
+import { Token } from "@znight/core";
+import { GuardEnforcement, HttpContext, RouteMetaCarrier } from "@znight/http";
+import { ConstValueNode, DocumentNode, GraphQLResolveInfo } from "graphql";
+/**
+ * GraphQL errors shown to clients (RFC 0005 §5.10, §8.8): `GraphQLException` and the
+ * `extensions.code` values the plugin produces (Apollo conventions, which clients already know).
+ *
+ * Import-free: the exception is a plain `Error` subclass, rendered by the runtime as
+ * `{ message, locations, path, extensions: { code, ...extensions } }`.
+ */
+/** `extensions.code` values produced by `@znight/graphql`. Applications may use their own codes too. */
+declare const GraphQLErrorCode: {
+  /** The document does not parse (syntax error, `limits.maxTokens`). */
+  readonly ParseFailed: "GRAPHQL_PARSE_FAILED";
+  /** The document is not valid against the schema. */
+  readonly ValidationFailed: "GRAPHQL_VALIDATION_FAILED";
+  /** Invalid variables or arguments (Standard Schema issues in `extensions.issues`), HTTP 400. */
+  readonly BadUserInput: "BAD_USER_INPUT";
+  /** The document exceeds `limits.maxDepth`, `maxAliases` or `maxDirectives`. */
+  readonly QueryTooComplex: "QUERY_TOO_COMPLEX";
+  /** HTTP 401. */
+  readonly Unauthenticated: "UNAUTHENTICATED";
+  /** A guard returned `false`, or HTTP 403. */
+  readonly Forbidden: "FORBIDDEN";
+  /** HTTP 404, or a key missing from `orderByKeys`. */
+  readonly NotFound: "NOT_FOUND";
+  /** HTTP 409. */
+  readonly Conflict: "CONFLICT";
+  /** HTTP 429. */
+  readonly TooManyRequests: "TOO_MANY_REQUESTS";
+  /** Any other HTTP 4xx. */
+  readonly BadRequest: "BAD_REQUEST";
+  /** A subscriber fell behind its buffer: its stream ends with this error. */
+  readonly SubscriptionOverflow: "SUBSCRIPTION_OVERFLOW";
+  /** Too many active subscriptions (`subscriptions.maxActive`), HTTP 503. */
+  readonly ServiceUnavailable: "SERVICE_UNAVAILABLE";
+  /** An unexpected error, masked (`Unexpected error.`) unless `exposeErrors`. */
+  readonly InternalServerError: "INTERNAL_SERVER_ERROR";
+};
+/** One of the {@link GraphQLErrorCode} values. */
+type GraphQLErrorCodeValue = (typeof GraphQLErrorCode)[keyof typeof GraphQLErrorCode];
+/** Options of {@link GraphQLException}. */
+interface GraphQLExceptionOptions {
+  /** `extensions.code` (`'NOT_FOUND'`, `'CONFLICT'`, or an application code). */
+  readonly code: GraphQLErrorCodeValue | (string & Record<never, never>);
+  /** Extra `extensions` entries, sent to the client (`code` always wins). */
+  readonly extensions?: Readonly<Record<string, unknown>>;
+  /**
+   * The original error: never sent, logged once at `error` level with the request id, the schema
+   * coordinate and the path when the exception is shown for a field.
+   */
+  readonly cause?: unknown;
+}
+/**
+ * An error whose message and extensions are sent to the client as they are (§5.10): throw it from a
+ * resolver or return it from a `GraphQLErrorMapper`.
+ *
+ * ```ts
+ * throw new GraphQLException(`No book ${id}`, { code: 'NOT_FOUND', extensions: { bookId: id } })
+ * ```
+ */
+declare class GraphQLException extends Error {
+  /** `extensions.code`. */
+  readonly code: string;
+  /** Extra `extensions` entries. */
+  readonly extensions: Readonly<Record<string, unknown>> | undefined;
+  constructor(message: string, options: GraphQLExceptionOptions);
+}
+/** Arguments of a field, after GraphQL coercion (and null handling, §7.3), by argument name. */
+type GraphQLArgs = Readonly<Record<string, unknown>>;
+/** Kind of a GraphQL operation. */
+type GraphQLOperationKind = "query" | "mutation" | "subscription";
+/** How an operation reached the server: GraphQL over HTTP, GraphQL over SSE, or `plugin.execute()`. */
+type GraphQLTransport = "http" | "sse" | "direct";
+/**
+ * Options of a loader (§5.5), read once per loader class: the `options` property of a
+ * {@link BatchLoad} provider. They are DataLoader's, except `batchScheduleFn` (Znight batches per
+ * tick of the execution).
+ */
+interface LoaderOptions<K = unknown> {
+  /** Largest number of keys passed to one `load()` call. Default: unlimited. */
+  readonly maxBatchSize?: number;
+  /** Cache values per execution (by key). Default `true`. */
+  readonly cache?: boolean;
+  /** Cache key of a key, for object keys (`key => key.id`). Default: the key itself. */
+  cacheKeyFn?(key: K): unknown;
+}
+/**
+ * A batch loader (§5.5): a provider that loads many keys at once. Inject its per-execution
+ * DataLoader with `@Loader() authors: Loader<AuthorsById>`.
+ *
+ * ```ts
+ * @Injectable()
+ * export class AuthorsById implements BatchLoad<ID, Author> {
+ *   constructor(private readonly authors: AuthorRepository) {}
+ *
+ *   async load(ids: readonly ID[]): Promise<readonly (Author | Error)[]> {
+ *     return orderByKeys(ids, await this.authors.findMany(ids), author => author.id)
+ *   }
+ * }
+ * ```
+ */
+interface BatchLoad<K, V> {
+  /**
+   * Loads the values of `keys`: one value (or an `Error` failing that key only) per key, in the
+   * order of the keys. Another number of values fails every key of the batch (ZNIGHT065).
+   */
+  load(keys: readonly K[]): Promise<readonly (V | Error)[]>;
+  /** DataLoader options, read once per loader class. */
+  readonly options?: LoaderOptions<K>;
+}
+/** Key type of a {@link BatchLoad} provider. */
+type LoaderKey<L> = L extends {
+  load(keys: readonly (infer K)[]): unknown;
+} ? K : never;
+/** Value type of a {@link BatchLoad} provider (`Error`s excluded). */
+type LoaderValue<L> = L extends {
+  load(keys: never): Promise<readonly (infer V)[]>;
+} ? Exclude<V, Error> : never;
+/**
+ * The DataLoader of one execution for a loader (§5.5): the part of the `dataloader` API resolvers
+ * use. `Loader<L>` (exported with the `@Loader()` decorator) is this view for the provider `L`.
+ */
+interface BatchLoader<K, V> {
+  /** The value of `key`, batched with the other keys requested in the same tick. */
+  load(key: K): Promise<V>;
+  /** The values of `keys`: a value or an `Error` per key, never a rejection. */
+  loadMany(keys: readonly K[]): Promise<(V | Error)[]>;
+  /** Forgets the cached value of `key`. */
+  clear(key: K): this;
+  /** Forgets every cached value. */
+  clearAll(): this;
+  /** Caches a value for `key` (no effect when `key` is already cached). */
+  prime(key: K, value: V | PromiseLike<V> | Error): this;
+}
+/** A class of {@link BatchLoad} providers. */
+type BatchLoadClass<L extends BatchLoad<unknown, unknown> = BatchLoad<unknown, unknown>> = abstract new (...args: never[]) => L;
+/**
+ * The context of one GraphQL operation (§5.8): a request-scoped external
+ * (`@znight/graphql#GraphQLContext`), injected with `@Ctx()` in resolvers, in request-scoped
+ * providers, or as `Lazy<GraphQLContext>` in singletons. It is not a bag for user data: the
+ * authenticated user is a request-scoped provider filled by a guard.
+ */
+interface GraphQLContext {
+  /** Id of the request carrying the operation (`HttpContext.requestId` over HTTP). */
+  readonly requestId: string;
+  readonly transport: GraphQLTransport;
+  /** The HTTP request carrying the operation; `undefined` for `plugin.execute()`. */
+  readonly http: HttpContext | undefined;
+  readonly operationType: GraphQLOperationKind;
+  readonly operationName: string | undefined;
+  /** The parsed (and validated) document, shared through the document cache: never mutate it. */
+  readonly document: DocumentNode;
+  readonly variables: Readonly<Record<string, unknown>>;
+  /**
+   * Over HTTP, the request's `ctx.signal` (RFC 0006): client gone, SSE stream closed on shutdown or
+   * `maxDuration`. Passed to graphql-js as `abortSignal`. Direct executions get the plugin's own.
+   * A subscription's also aborts when its stream ends (the source ended, or `return()`).
+   */
+  readonly signal: AbortSignal;
+  /** Per-operation storage. */
+  readonly state: Map<string | symbol, unknown>;
+  /** The DataLoader of the current execution for a loader class (`ctx.loader(AuthorsById)`). */
+  loader<L extends BatchLoad<unknown, unknown>>(loader: BatchLoadClass<L>): BatchLoader<LoaderKey<L>, LoaderValue<L>>;
+  /**
+   * The DataLoader of the current execution for a loader provider token: what the generated
+   * `invoke` functions call (`c.loader('src/a.loader.ts#AuthorsById')`), with no class lookup.
+   */
+  loader(token: Token): BatchLoader<unknown, unknown>;
+}
+/**
+ * What a {@link GraphQLGuard} receives for one resolver call (§5.9). It satisfies the
+ * `RouteMetaCarrier` of `@znight/http`, so route decorators read it: `Roles.get(ctx)`.
+ */
+interface ResolverContext<TParent = unknown, TArgs extends GraphQLArgs = GraphQLArgs> extends RouteMetaCarrier {
+  /** Effective metadata of the field (method decisions over class decisions) and its schema coordinate. */
+  readonly route: {
+    readonly meta: Readonly<Record<string, unknown>>;
+    /** `Query.books`, `Book.author`. */
+    readonly coordinate: string;
+  };
+  /** The operation. */
+  readonly operation: GraphQLContext;
+  /** Name of the type owning the field (`Query`, `Book`). */
+  readonly parentType: string;
+  /** Name of the field. */
+  readonly field: string;
+  readonly args: TArgs;
+  /** The parent object (`undefined` for root fields, unless a root value is configured). */
+  readonly parent: TParent;
+  readonly info: GraphQLResolveInfo;
+  /** `operation.http`. */
+  readonly http: HttpContext | undefined;
+}
+/**
+ * A guard of GraphQL fields (§5.9). Guards run global (plugin option) → class `@UseGuard` → method
+ * `@UseGuard`; `false` fails the field with a `FORBIDDEN` error, a thrown error is mapped (§5.10).
+ * One class may also implement `CanActivate` (HTTP routes).
+ */
+interface GraphQLGuard {
+  canResolve(ctx: ResolverContext): boolean | Promise<boolean>;
+}
+/** A class producing {@link GraphQLGuard}s, with the route decorators it enforces (`static enforces`). */
+type GraphQLGuardClass = (abstract new (...args: never[]) => GraphQLGuard) & GuardEnforcement;
+/**
+ * Converts application errors to GraphQL errors (§5.10). Mappers are tried in order for every
+ * error of `errors[]` that is not a `GraphQLException` already; the first one returning an
+ * exception wins, `undefined` passes. Synchronous: errors are formatted once the execution
+ * finished, without an extra await per error.
+ */
+interface GraphQLErrorMapper {
+  map(error: unknown, ctx: GraphQLContext): GraphQLException | undefined;
+}
+/** A class producing {@link GraphQLErrorMapper}s. */
+type GraphQLErrorMapperClass = abstract new (...args: never[]) => GraphQLErrorMapper;
+/**
+ * Turns the errors of a field into values of the field (errors as data, RFC 0008). It applies to
+ * the resolver-backed fields whose type is a union holding one of the object types it declares
+ * (`static types`), decided at boot; every other field keeps its errors in `errors[]`.
+ *
+ * ```ts
+ * @Injectable()
+ * export class Rejections implements GraphQLResultMapper {
+ *   static readonly types = ['NotFoundRejection']
+ *
+ *   toResult(error: unknown): NotFoundRejection | undefined {
+ *     if (error instanceof NotFoundException) return { __typename: 'NotFoundRejection', message: error.message }
+ *     return undefined
+ *   }
+ * }
+ * ```
+ */
+interface GraphQLResultMapper {
+  /**
+   * The value of the field for `error`: an object of a member of the field's union, or `undefined`
+   * to leave the error to the next mapper, then to `errors[]`. Synchronous. `error` is the raw
+   * error, a `GraphQLException` included (a guard returning `false` is `FORBIDDEN`, a Standard
+   * Schema failure of the arguments `BAD_USER_INPUT` with `extensions.issues`).
+   */
+  toResult(error: unknown, ctx: ResolverContext): unknown;
+}
+/** The object types a result mapper may produce: names of object types of the schema. */
+interface GraphQLResultTypes {
+  readonly types: readonly string[];
+}
+/** A class producing {@link GraphQLResultMapper}s, with the object types it produces (`static types`). */
+type GraphQLResultMapperClass = (abstract new (...args: never[]) => GraphQLResultMapper) & GraphQLResultTypes;
+/**
+ * The implementation of a custom scalar (§5.7), given to `scalar<T>(name, definition)`. The
+ * runtime maps it to graphql-js 17 `GraphQLScalarType` coercers: `serialize` → `coerceOutputValue`,
+ * `parseValue` → `coerceInputValue`, `parseLiteral` → `coerceInputLiteral` (the deprecated
+ * graphql-js names are never passed on).
+ */
+interface ScalarDefinition<T> {
+  readonly description?: string;
+  /** URL of the specification of the scalar (`@specifiedBy`). */
+  readonly specifiedByURL?: string;
+  /** Internal value → response value. */
+  serialize(value: T): unknown;
+  /** Variable value (JSON) → internal value; throw to reject it. */
+  parseValue(value: unknown): T;
+  /** Literal of the document → internal value. Default: `parseValue` of the literal's JSON value. */
+  parseLiteral?(literal: ConstValueNode): T;
+}
+export { GraphQLExceptionOptions as C, GraphQLException as S, LoaderValue as _, GraphQLContext as a, GraphQLErrorCode as b, GraphQLGuard as c, GraphQLResultMapper as d, GraphQLResultMapperClass as f, LoaderOptions as g, LoaderKey as h, GraphQLArgs as i, GraphQLGuardClass as l, GraphQLTransport as m, BatchLoadClass as n, GraphQLErrorMapper as o, GraphQLResultTypes as p, BatchLoader as r, GraphQLErrorMapperClass as s, BatchLoad as t, GraphQLOperationKind as u, ResolverContext as v, GraphQLErrorCodeValue as x, ScalarDefinition as y };
+//# sourceMappingURL=types-DQ713UgI.d.mts.map

package/package.json

@@ -1 +1,97 @@
-{ "name": "@znight/graphql", "version": "0.0.0", "license": "MIT", "repository": { "type": "git", "url": "git+https://github.com/znight-org/znight.git" } }
+{
+  "name": "@znight/graphql",
+  "version": "0.2.1",
+  "description": "Znight GraphQL: code-first GraphQL whose schema is derived from TypeScript types at build time, on graphql-js 17",
+  "license": "MIT",
+  "author": "Ugho STEPHAN",
+  "homepage": "https://github.com/znight-org/znight/tree/main/packages/graphql#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/znight-org/znight.git",
+    "directory": "packages/graphql"
+  },
+  "bugs": "https://github.com/znight-org/znight/issues",
+  "keywords": ["znight", "graphql", "code-first", "dataloader", "subscriptions", "sse"],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "@znight/source": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./compiler": {
+      "@znight/source": "./src/compiler/index.ts",
+      "types": "./dist/compiler.d.mts",
+      "default": "./dist/compiler.mjs"
+    },
+    "./testing": {
+      "@znight/source": "./src/testing.ts",
+      "types": "./dist/testing.d.mts",
+      "default": "./dist/testing.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p test",
+    "test": "bun test --conditions=@znight/source test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@znight/core": "0.2.1",
+    "dataloader": "^2.2.3"
+  },
+  "peerDependencies": {
+    "@znight/http": "^0.2.1",
+    "@znight/compiler": "^0.2.1",
+    "@znight/testing": "^0.2.1",
+    "graphql": "^17.0.2"
+  },
+  "peerDependenciesMeta": {
+    "@znight/compiler": {
+      "optional": true
+    },
+    "@znight/testing": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@znight/http": "0.2.1",
+    "@znight/compiler": "0.2.1",
+    "@znight/testing": "0.2.1",
+    "graphql": "17.0.2",
+    "graphql-http": "1.23.1",
+    "graphql-sse": "2.6.3",
+    "valibot": "1.5.0",
+    "zod": "4.6.7"
+  },
+  "znight": {
+    "apiVersion": 1,
+    "compiler": "@znight/graphql/compiler",
+    "provides": [
+      {
+        "export": "GraphQLContext",
+        "plugin": "GraphQLPlugin",
+        "scope": "request"
+      },
+      {
+        "export": "PubSub",
+        "plugin": "GraphQLPlugin",
+        "scope": "singleton"
+      },
+      {
+        "export": "GraphQLPlugin",
+        "plugin": "GraphQLPlugin",
+        "scope": "singleton"
+      }
+    ]
+  }
+}