@znight/core 0.1.3 → 0.2.0

package/README.md

@@ -338,12 +338,13 @@ return what is known (`[]`).
 declared in core, so producers and observers (`@znight/observability`, your plugins) share them
 without depending on each other:
 
-| Hook                | Event                  | Produced by                                                                  |
-| ------------------- | ---------------------- | ---------------------------------------------------------------------------- |
-| `http:request`      | `HttpRequestEvent`     | `@znight/http`, one request                                                  |
-| `messaging:message` | `MessageDeliveryEvent` | `@znight/messaging`, one delivery                                            |
-| `messaging:publish` | `MessagePublishEvent`  | `@znight/messaging`, one `MessageBroker` publication                         |
-| `schedule:run`      | `ScheduledRunEvent`    | `@znight/schedule`, one occurrence of a job (executed or not, see `outcome`) |
+| Hook                | Event                   | Produced by                                                                  |
+| ------------------- | ----------------------- | ---------------------------------------------------------------------------- |
+| `http:request`      | `HttpRequestEvent`      | `@znight/http`, one request                                                  |
+| `messaging:message` | `MessageDeliveryEvent`  | `@znight/messaging`, one delivery                                            |
+| `messaging:publish` | `MessagePublishEvent`   | `@znight/messaging`, one `MessageBroker` publication                         |
+| `schedule:run`      | `ScheduledRunEvent`     | `@znight/schedule`, one occurrence of a job (executed or not, see `outcome`) |
+| `graphql:operation` | `GraphQLOperationEvent` | `@znight/graphql` (planned, RFC 0005), one GraphQL operation                 |
 
 `ScheduledRunEvent` carries `job`, `kind` (`cron` / `interval` / `timeout`), `host`, `method`,
 `runId`, `trigger` (`schedule` / `start` / `manual` / `queued`), `scheduledAt` (epoch ms),
@@ -358,6 +359,13 @@ wrappers waited (job removed or paused, scheduler stopping), or a wrapper threw
 rejects). The producer settles it after `hooks.run` (`skipped`, or `failed` for a wrapper that
 threw), so a wrapper that reports it reads `event.outcome ?? (nextRejected ? 'failed' : 'skipped')`.
 
+`GraphQLOperationEvent` carries `operationType` (`query` / `mutation` / `subscription`, `undefined`
+when the request was rejected before an operation was selected), `operationName`, `documentId`
+(SHA-256 of the query text), `transport` (`http` / `sse` / `direct`), `requestId`, `context` (the
+`GraphQLContext`), `startTime`, and, once settled, `outcome` (`success` / `partial` / `error` /
+`rejected`) and `errors` (`{ message, code, path? }`, as sent to the client). A subscription is one
+operation from its start to its end.
+
 Other packages declare their hooks by augmenting `ZnightHooks`:
 
 ```ts
@@ -421,6 +429,6 @@ the [architecture specification](../../docs/internals/architecture.md#48-validat
 The catalogue is shared by the compiler and every first-party package. `ZNIGHT001`–`ZNIGHT029`
 belong to the core, the compiler and the features of the first release (`ZNIGHT023`, a missing
 route decision, is reported by `@znight/http`). From `ZNIGHT030`, each package owns a block of ten:
-`ZNIGHT030`–`039` `@znight/openapi`, `ZNIGHT040`–`049` `@znight/schedule` (`050`–`059` and
-`060`–`069` are reserved for `@znight/websocket` and `@znight/graphql`, planned for v0.2). Inside a
-block, codes are allocated in order; third-party packages get no `ZNIGHT` code.
+`ZNIGHT030`–`039` `@znight/openapi`, `ZNIGHT040`–`049` `@znight/schedule`, `ZNIGHT060`–`069`
+`@znight/graphql` (RFC 0005, planned for v0.2; `050`–`059` are reserved for `@znight/websocket`).
+Inside a block, codes are allocated in order; third-party packages get no `ZNIGHT` code.

package/dist/index.d.mts

@@ -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
@@ -96,6 +96,32 @@ export declare const ErrorCode: {
   readonly MissingLockStore: "ZNIGHT043";
   /** A scheduled run was aborted (`ctx.signal.reason`, `JobAbortedError`); never thrown by the framework. */
   readonly JobAborted: "ZNIGHT044";
+  /** A TypeScript type cannot be mapped to a GraphQL type, or a resolver lacks the annotation it needs. */
+  readonly InvalidGraphQLType: "ZNIGHT060";
+  /** Two declarations or root fields share a GraphQL name, or a name is invalid or reserved. */
+  readonly GraphQLNameConflict: "ZNIGHT061";
+  /**
+   * Invalid resolver structure: `@ResolveField` without `@Parent()`, a subscription not returning an
+   * async iterable, no `@Query`, inherited handlers, resolvers in a compiled library.
+   */
+  readonly 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.
+   */
+  readonly InvalidGraphQLInput: "ZNIGHT063";
+  /** The members of a GraphQL union cannot be told apart at runtime. */
+  readonly 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.
+   */
+  readonly InvalidLoader: "ZNIGHT065";
+  /**
+   * Invalid GraphQL setup at boot: malformed or version-skewed metadata, invalid schema, invalid
+   * `GraphQLPlugin` options, missing `HttpPlugin`, scalar name mismatch.
+   */
+  readonly InvalidGraphQLSetup: "ZNIGHT066";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** Short human readable description of every error code. */
@@ -610,6 +636,12 @@ 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;
 }
 /**
  * Instrumentation event of the `http:request` hook. Defined in core so that producers
@@ -737,6 +769,54 @@ interface ScheduledRunEvent {
   /** Set when the run's signal was aborted. */
   aborted?: ScheduledRunAbortReason;
 }
+/** Type of a GraphQL operation (`GraphQLOperationEvent.operationType`). */
+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).
+ */
+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).
+ */
+type GraphQLOperationOutcome = "success" | "partial" | "error" | "rejected";
+/** One error of a GraphQL response, as sent to the client (masked when it is unexpected). */
+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.
+ */
+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. */
 type HookName = keyof ZnightHooks;
 /** Event type of hook `K`. */
@@ -1094,5 +1174,5 @@ export declare class ZnightAggregateError extends ZnightError {
  * that were attached to it instead of being thrown. Empty when there are none.
  */
 export declare function getSuppressedErrors(error: unknown): readonly unknown[];
-export type { ApplicationOptions, ApplicationState, ClassKey, ClassMarker, ConsoleLike, ConsoleLoggerOptions, CoreLogger, HookEvent, HookListener, HookName, HookWrapper, HooksOptions, HotContext, HttpRequestEvent, InitOptions, InjectableOptions, InterceptMethodOptions, InterceptOptionsArgs, InterceptorClass, InterceptorLink, LogContext, LogLevel, ManagedInstance, MessageDeliveryEvent, MessagePublishEvent, MethodInterceptor, MethodInvocation, MethodMarker, OnReady, OnStart, OnStop, OpenedScope, ParameterMarker, Plugin, PluginContext, PluginHook, PluginOptions, PluginRootsContext, ProcessLike, ProviderKey, ProviderValues, ProvidesOptions, ScheduledRunAbortReason, ScheduledRunEvent, ScheduledRunOutcome, ScheduledRunTrigger, ScopeContext, ScopeValues, ShutdownOptions, ShutdownSignal, TypedToken, ZnightHooks };
+export type { ApplicationOptions, ApplicationState, ClassKey, ClassMarker, ConsoleLike, ConsoleLoggerOptions, CoreLogger, GraphQLOperationError, GraphQLOperationEvent, GraphQLOperationOutcome, GraphQLOperationTransport, GraphQLOperationType, HookEvent, HookListener, HookName, HookWrapper, HooksOptions, HotContext, HttpRequestEvent, InitOptions, InjectableOptions, InterceptMethodOptions, InterceptOptionsArgs, InterceptorClass, InterceptorLink, LogContext, LogLevel, ManagedInstance, MessageDeliveryEvent, MessagePublishEvent, MethodInterceptor, MethodInvocation, MethodMarker, OnReady, OnStart, OnStop, OpenedScope, ParameterMarker, Plugin, PluginContext, PluginHook, PluginOptions, PluginRootsContext, ProcessLike, ProviderKey, ProviderValues, ProvidesOptions, ScheduledRunAbortReason, ScheduledRunEvent, ScheduledRunOutcome, ScheduledRunTrigger, ScopeContext, ScopeValues, ShutdownOptions, ShutdownSignal, TypedToken, ZnightHooks };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -9,7 +9,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 *   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
@@ -97,7 +97,33 @@ const ErrorCode = {
 	/** A job requires a lock but `SchedulePlugin` has no lock store. */
 	MissingLockStore: "ZNIGHT043",
 	/** A scheduled run was aborted (`ctx.signal.reason`, `JobAbortedError`); never thrown by the framework. */
-	JobAborted: "ZNIGHT044"
+	JobAborted: "ZNIGHT044",
+	/** 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"
 };
 /** Short human readable description of every error code. */
 const ERROR_DESCRIPTIONS = {
@@ -136,7 +162,14 @@ const ERROR_DESCRIPTIONS = {
 	ZNIGHT041: "Duplicate job: two jobs share a name",
 	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)"
+	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"
 };
 /** Base class of every error thrown by Znight at runtime. */
 var ZnightError = class extends Error {