@znight/core 0.1.3 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@znight/core",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Znight core runtime: compile-time DI container, lifecycle, plugins and marker decorators",
   "license": "MIT",
   "author": "Ugho STEPHAN",

package/src/errors.ts

@@ -7,7 +7,7 @@
  *   messaging, config, observability).
  * - From `ZNIGHT030`, each first-party package reserves a block of ten: `ZNIGHT030`–`039`
  *   `@znight/openapi`, `ZNIGHT040`–`049` `@znight/schedule`, `ZNIGHT050`–`059` `@znight/websocket`
- *   (reserved), `ZNIGHT060`–`069` `@znight/graphql` (reserved).
+ *   (reserved), `ZNIGHT060`–`069` `@znight/graphql`.
  *
  * Within a range, codes are allocated in order without gaps. A package uses its block for its own
  * failure modes, with one catch-all code for invalid usage and options, and reuses a lower code
@@ -100,6 +100,34 @@ export const ErrorCode = {
   MissingLockStore: 'ZNIGHT043',
   /** A scheduled run was aborted (`ctx.signal.reason`, `JobAbortedError`); never thrown by the framework. */
   JobAborted: 'ZNIGHT044',
+
+  // ZNIGHT060–069: @znight/graphql (RFC 0005)
+  /** A TypeScript type cannot be mapped to a GraphQL type, or a resolver lacks the annotation it needs. */
+  InvalidGraphQLType: 'ZNIGHT060',
+  /** Two declarations or root fields share a GraphQL name, or a name is invalid or reserved. */
+  GraphQLNameConflict: 'ZNIGHT061',
+  /**
+   * Invalid resolver structure: `@ResolveField` without `@Parent()`, a subscription not returning an
+   * async iterable, no `@Query`, inherited handlers, resolvers in a compiled library.
+   */
+  InvalidResolver: 'ZNIGHT062',
+  /**
+   * Invalid input position: a type used as input and output, a getter, a union, a cycle of non-null
+   * input fields, a default value not matching its type.
+   */
+  InvalidGraphQLInput: 'ZNIGHT063',
+  /** The members of a GraphQL union cannot be told apart at runtime. */
+  UnresolvableAbstractType: 'ZNIGHT064',
+  /**
+   * Invalid loader: `@Loader()` on a type that is not `Loader<L>`, `L` not a `BatchLoad`; at runtime,
+   * a batch function returning another number of values than keys.
+   */
+  InvalidLoader: 'ZNIGHT065',
+  /**
+   * Invalid GraphQL setup at boot: malformed or version-skewed metadata, invalid schema, invalid
+   * `GraphQLPlugin` options, missing `HttpPlugin`, scalar name mismatch.
+   */
+  InvalidGraphQLSetup: 'ZNIGHT066',
 } as const
 
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode]
@@ -142,6 +170,13 @@ export const ERROR_DESCRIPTIONS: Readonly<Record<ErrorCode, string>> = {
   ZNIGHT042: 'Unknown job: no job has this name',
   ZNIGHT043: 'Missing lock store: a job requires a lock but SchedulePlugin has no store',
   ZNIGHT044: 'Job aborted: a scheduled run was aborted (timeout, lost lock, removal or shutdown)',
+  ZNIGHT060: 'Invalid GraphQL type: a TypeScript type cannot be mapped to a GraphQL type',
+  ZNIGHT061: 'GraphQL name conflict: two types or root fields share a name, or a name is invalid or reserved',
+  ZNIGHT062: 'Invalid resolver: the structure of a GraphQL resolver is invalid',
+  ZNIGHT063: 'Invalid GraphQL input: a type cannot be used in an input position',
+  ZNIGHT064: 'Unresolvable abstract type: the members of a GraphQL union cannot be told apart at runtime',
+  ZNIGHT065: 'Invalid loader: not a Loader of a BatchLoad provider, or a batch returning the wrong number of values',
+  ZNIGHT066: 'Invalid GraphQL setup: metadata, schema, GraphQLPlugin options or HttpPlugin missing',
 }
 
 export interface ZnightErrorOptions extends ErrorOptions {

package/src/hooks.ts

@@ -27,6 +27,12 @@ export interface ZnightHooks {
    * drop, a wrapper that threw first): see `ScheduledRunEvent.outcome`.
    */
   'schedule:run': ScheduledRunEvent
+  /**
+   * One GraphQL operation handled by `@znight/graphql` (RFC 0005): a query or a mutation, or a whole
+   * subscription from its start to its end. Wrapped with `hooks.run` when wrappers exist, then
+   * emitted when listeners exist.
+   */
+  'graphql:operation': GraphQLOperationEvent
 }
 
 /**
@@ -162,6 +168,59 @@ export interface ScheduledRunEvent {
   aborted?: ScheduledRunAbortReason
 }
 
+/** Type of a GraphQL operation (`GraphQLOperationEvent.operationType`). */
+export type GraphQLOperationType = 'query' | 'mutation' | 'subscription'
+
+/**
+ * How a GraphQL operation reached the server (`GraphQLOperationEvent.transport`): GraphQL over HTTP,
+ * GraphQL over Server-Sent Events, or a direct call (`execute()` / `subscribe()` of the plugin).
+ */
+export type GraphQLOperationTransport = 'http' | 'sse' | 'direct'
+
+/**
+ * Outcome of a GraphQL operation (`GraphQLOperationEvent.outcome`):
+ *
+ * - `'success'`: executed, no error;
+ * - `'partial'`: executed, with data and field errors;
+ * - `'error'`: executed, without data (a non-null root field failed, or the execution threw);
+ * - `'rejected'`: never executed (parse, validation, variable coercion or limit errors).
+ */
+export type GraphQLOperationOutcome = 'success' | 'partial' | 'error' | 'rejected'
+
+/** One error of a GraphQL response, as sent to the client (masked when it is unexpected). */
+export interface GraphQLOperationError {
+  readonly message: string
+  /** `extensions.code` of the error (`FORBIDDEN`, `GRAPHQL_PARSE_FAILED`...). */
+  readonly code: string | undefined
+  /** Response path of the field that failed; absent for request errors. */
+  readonly path?: readonly (string | number)[]
+}
+
+/**
+ * Instrumentation event of the `graphql:operation` hook, produced by `@znight/graphql` (RFC 0005)
+ * once per operation. For a subscription, it covers its whole life: wrappers see it start, and
+ * `outcome` is set when it ends. Mutable fields are filled in by the producer before `hooks.run`
+ * resolves; listeners see the final values.
+ */
+export interface GraphQLOperationEvent {
+  /** `undefined` when the request was rejected before an operation was selected (parse error...). */
+  readonly operationType: GraphQLOperationType | undefined
+  /** `undefined` for an anonymous operation, or when none was selected. */
+  readonly operationName: string | undefined
+  /** SHA-256 (hex) of the query text, cached with the parsed document; `undefined` without a query. */
+  readonly documentId: string | undefined
+  readonly transport: GraphQLOperationTransport
+  readonly requestId: string
+  /** `GraphQLContext` from `@znight/graphql`. */
+  readonly context: unknown
+  /** `performance.now()` when the operation started. */
+  readonly startTime: number
+  /** Outcome, set before `hooks.run` resolves. */
+  outcome?: GraphQLOperationOutcome
+  /** Errors of the response (field and request errors), set before `hooks.run` resolves. */
+  errors?: readonly GraphQLOperationError[]
+}
+
 /** Name of a declared hook. */
 export type HookName = keyof ZnightHooks
 

package/src/index.ts

@@ -38,6 +38,11 @@ export {
 export { isProviderDefinition } from './definition.ts'
 export * from './errors.ts'
 export {
+  type GraphQLOperationError,
+  type GraphQLOperationEvent,
+  type GraphQLOperationOutcome,
+  type GraphQLOperationTransport,
+  type GraphQLOperationType,
   type HookEvent,
   type HookListener,
   type HookName,