@znight/core 0.1.2 → 0.1.4

package/README.md

@@ -238,6 +238,18 @@ Scopes are isolated with `AsyncLocalStorage` (concurrent requests never share in
 request-scoped provider outside of a scope throws `ZNIGHT013`. `container.currentScope()` exposes the
 active scope (`get`, `set`, `has`). Plugins (HTTP, messaging) open the scopes for you.
 
+`container.openScope(values?)` opens the same scope without a callback, for hot paths that stay
+synchronous as long as their work is (the HTTP pipeline): `run(fn, ...args)` calls `fn` in the scope
+and returns its result (its continuations stay in the scope), `close()` disposes the instances created
+in it. `close()` returns `undefined` when there is nothing to dispose, otherwise a promise that
+rejects with `ZNIGHT021` when a disposal fails; it must be called once the work is over.
+
+```ts
+const scope = container.openScope([['@znight/http#HttpContext', ctx]])
+const user = scope.run(() => container.get(CurrentUser).name)
+await scope.close()
+```
+
 ## Lazy dependencies
 
 `Lazy<T>` injects a handle resolved at call time, in the current scope. It breaks cycles and lets a
@@ -326,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),
@@ -346,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
@@ -409,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. */
@@ -399,6 +425,29 @@ interface ManagedInstance {
 }
 /** Seed values of a request scope: token-keyed pairs (aliases and known classes are accepted). */
 type ScopeValues = Iterable<readonly [ProviderKey, unknown]>;
+/**
+ * A request scope opened with {@link Container.openScope}: its owner runs code in it with
+ * {@link OpenedScope.run} and ends it with {@link OpenedScope.close}. The callback-free form of
+ * {@link Container.runInScope}, for hot paths that stay synchronous as long as their work is (the
+ * HTTP pipeline): no promise is created unless something is asynchronous.
+ */
+interface OpenedScope {
+  /** The values of the scope (what `currentScope()` returns in {@link run}). */
+  readonly context: ScopeContext;
+  /**
+   * Calls `fn(...args)` in the scope and returns its result. The code it runs and the asynchronous
+   * continuations it creates (awaits, promise callbacks, timers) see the scope, like the callback
+   * of `runInScope`. May be called several times until the scope is closed.
+   */
+  run<A extends readonly unknown[], R>(fn: (...args: A) => R, ...args: A): R;
+  /**
+   * Closes the scope (a later resolution of a request-scoped provider in it throws ZNIGHT013) and
+   * disposes the instances created in it, in reverse creation order. Returns `undefined` when no
+   * instance was created (nothing to wait for), otherwise a promise rejecting with ZNIGHT021 when a
+   * disposal fails. Idempotent: later calls return the first result.
+   */
+  close(): Promise<void> | undefined;
+}
 /**
  * The dependency injection container. It consumes the metadata generated by `@znight/compiler`:
  * no reflection happens at runtime, factories are called in a precomputed order and resolving a
@@ -500,6 +549,12 @@ export declare class Container {
    * disposal failed.
    */
   runInScope<R>(fn: () => R | Promise<R>, values?: ScopeValues): Promise<R>;
+  /**
+   * Opens a request scope seeded with `values`, like {@link runInScope}, but without running
+   * anything: the caller runs code in it (`run`) and closes it (`close`) when the work it started
+   * is over. Request-scoped providers resolved in it are disposed by `close`, which must be called.
+   */
+  openScope(values?: ScopeValues): OpenedScope;
   /** The active request scope, if any. */
   currentScope(): ScopeContext | undefined;
   /**
@@ -581,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
@@ -708,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`. */
@@ -1065,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, 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 {
@@ -809,12 +842,30 @@ function lifecycleError(step, error) {
 // src/scope.ts
 /** Implementation of {@link ScopeContext} used by the container (internal). */
 var RequestScope = class {
-	values = /* @__PURE__ */ new Map();
 	created = [];
 	closed = false;
 	#canonical;
-	constructor(canonical) {
+	#values;
+	/** Seed values not yet in {@link values}: canonical tokens and values, alternately. */
+	#seeds;
+	/** `seeds`: canonical tokens and their values, alternately (copied into {@link values} on first use). */
+	constructor(canonical, seeds) {
 		this.#canonical = canonical;
+		this.#seeds = seeds;
+	}
+	/** The values of the scope by canonical token: the seeds, then what was set or created in it. */
+	get values() {
+		let values = this.#values;
+		if (values === void 0) {
+			values = /* @__PURE__ */ new Map();
+			const seeds = this.#seeds;
+			if (seeds !== void 0) {
+				for (let index = 0; index < seeds.length; index += 2) values.set(seeds[index], seeds[index + 1]);
+				this.#seeds = void 0;
+			}
+			this.#values = values;
+		}
+		return values;
 	}
 	get(key) {
 		return this.values.get(this.#canonical(key));
@@ -1309,10 +1360,24 @@ var Container = class Container {
 		if (errors.length > 0) throw new ZnightAggregateError(ErrorCode.LifecycleFailed, `Failed to dispose ${errors.length} request-scoped instance(s)`, errors);
 		return result;
 	}
+	/**
+	* Opens a request scope seeded with `values`, like {@link runInScope}, but without running
+	* anything: the caller runs code in it (`run`) and closes it (`close`) when the work it started
+	* is over. Request-scoped providers resolved in it are disposed by `close`, which must be called.
+	*/
+	openScope(values) {
+		let seeds;
+		if (values !== void 0) {
+			seeds = [];
+			for (const [key, value] of values) seeds.push(this.#canonical(key), value);
+		}
+		return new ScopeHandle(this.#storage, new RequestScope(this.#canonical, seeds), this.#closeScopeFn);
+	}
 	/** The active request scope, if any. */
 	currentScope() {
 		return this.#storage.getStore();
 	}
+	#closeScopeFn = (scope) => this.#closeScope(scope);
 	async #closeScope(scope) {
 		scope.closed = true;
 		const errors = [];
@@ -1551,6 +1616,38 @@ function disposeQuietly(instance, method) {
 		if (isThenable(result)) result.then(void 0, () => void 0);
 	} catch {}
 }
+/** Implementation of {@link OpenedScope}. */
+var ScopeHandle = class {
+	#storage;
+	#scope;
+	#dispose;
+	#closed = false;
+	#closing;
+	constructor(storage, scope, dispose) {
+		this.#storage = storage;
+		this.#scope = scope;
+		this.#dispose = dispose;
+	}
+	get context() {
+		return this.#scope;
+	}
+	run(fn, ...args) {
+		return this.#storage.run(this.#scope, fn, ...args);
+	}
+	close() {
+		if (this.#closed) return this.#closing;
+		this.#closed = true;
+		const scope = this.#scope;
+		if (scope.created.length === 0) {
+			scope.closed = true;
+			return;
+		}
+		this.#closing = this.#dispose(scope).then((errors) => {
+			if (errors.length > 0) throw new ZnightAggregateError(ErrorCode.LifecycleFailed, `Failed to dispose ${errors.length} request-scoped instance(s)`, errors);
+		});
+		return this.#closing;
+	}
+};
 // src/hooks.ts
 const EMPTY = Object.freeze([]);
 /**