@znight/core 0.1.2 → 0.1.4

package/package.json

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

package/src/container.ts

@@ -93,6 +93,30 @@ export interface ManagedInstance {
 /** Seed values of a request scope: token-keyed pairs (aliases and known classes are accepted). */
 export 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.
+ */
+export 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
+}
+
 type Status = 'open' | 'initializing' | 'ready' | 'failed' | 'disposed'
 
 interface InitRun {
@@ -706,11 +730,27 @@ export class Container {
     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?: ScopeValues): OpenedScope {
+    let seeds: unknown[] | undefined
+    if (values !== undefined) {
+      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(): ScopeContext | undefined {
     return this.#storage.getStore()
   }
 
+  readonly #closeScopeFn = (scope: RequestScope): Promise<unknown[]> => this.#closeScope(scope)
+
   async #closeScope(scope: RequestScope): Promise<unknown[]> {
     scope.closed = true
     const errors: unknown[] = []
@@ -1011,3 +1051,50 @@ function disposeQuietly(instance: unknown, method: string | undefined): void {
     // best effort
   }
 }
+
+/** Implementation of {@link OpenedScope}. */
+class ScopeHandle implements OpenedScope {
+  readonly #storage: AsyncLocalStorage<RequestScope>
+  readonly #scope: RequestScope
+  readonly #dispose: (scope: RequestScope) => Promise<unknown[]>
+  #closed = false
+  #closing: Promise<void> | undefined
+
+  constructor(
+    storage: AsyncLocalStorage<RequestScope>,
+    scope: RequestScope,
+    dispose: (scope: RequestScope) => Promise<unknown[]>,
+  ) {
+    this.#storage = storage
+    this.#scope = scope
+    this.#dispose = dispose
+  }
+
+  get context(): ScopeContext {
+    return this.#scope
+  }
+
+  run<A extends readonly unknown[], R>(fn: (...args: A) => R, ...args: A): R {
+    return this.#storage.run(this.#scope, fn, ...args)
+  }
+
+  close(): Promise<void> | undefined {
+    if (this.#closed) return this.#closing
+    this.#closed = true
+    const scope = this.#scope
+    if (scope.created.length === 0) {
+      scope.closed = true
+      return undefined
+    }
+    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
+  }
+}

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

@@ -17,7 +17,7 @@ export {
   type ProviderValues,
   type ShutdownOptions,
 } from './application.ts'
-export { Container, type InitOptions, type ManagedInstance, type ScopeValues } from './container.ts'
+export { Container, type InitOptions, type ManagedInstance, type OpenedScope, type ScopeValues } from './container.ts'
 export {
   type ClassMarker,
   Factory,
@@ -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,

package/src/scope.ts

@@ -26,13 +26,32 @@ export interface ScopedInstance {
 
 /** Implementation of {@link ScopeContext} used by the container (internal). */
 export class RequestScope implements ScopeContext {
-  readonly values: Map<Token, unknown> = new Map()
   readonly created: ScopedInstance[] = []
   closed = false
   readonly #canonical: (key: ProviderKey) => Token
+  #values: Map<Token, unknown> | undefined
+  /** Seed values not yet in {@link values}: canonical tokens and values, alternately. */
+  #seeds: readonly unknown[] | undefined
 
-  constructor(canonical: (key: ProviderKey) => Token) {
+  /** `seeds`: canonical tokens and their values, alternately (copied into {@link values} on first use). */
+  constructor(canonical: (key: ProviderKey) => Token, seeds?: readonly unknown[]) {
     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(): Map<Token, unknown> {
+    let values = this.#values
+    if (values === undefined) {
+      values = new Map()
+      const seeds = this.#seeds
+      if (seeds !== undefined) {
+        for (let index = 0; index < seeds.length; index += 2) values.set(seeds[index] as Token, seeds[index + 1])
+        this.#seeds = undefined
+      }
+      this.#values = values
+    }
+    return values
   }
 
   get<T = unknown>(key: ProviderKey<T>): T | undefined {