@zudojs/api 1.2.1 → 1.2.3

package/README.md

@@ -59,6 +59,7 @@ import {
   type APIExecutionContext,
   type APIExecutorOptions,
   type APIHandler,
+  type APIHandlerContext,
   type APIInterceptor,
   type APIOperation,
   type APIOperationMetadata,
@@ -308,6 +309,8 @@ Every operation has a deadline. `timeout` must be a positive, finite integer of
 
 The handler always receives a `context.signal`, even when the caller supplied none. It aborts when the deadline elapses (its `reason` is the `APITimeoutError` the call fails with, 504) or when the caller's signal aborts (its `reason` is the `ErrorCode.OPERATION_CANCELLED` error the call fails with), so pass it into anything that supports it (`fetch`, a driver query, a loop check) and the work stops instead of running on and repeating side effects after the caller has given up. The signal is not aborted when the handler completes normally. Everything else on the handler's context (`requestId`, `state`, `get`/`set`, `metadata`) is the caller's context. Branch on `ErrorCode.OPERATION_CANCELLED` rather than on the (nginx-convention) 499 status.
 
+The type says so too: a handler's context is `APIHandlerContext` (`APIContext & { readonly signal: AbortSignal }`), so `context.signal` needs no `!` under strict TypeScript. Only the handler's view is narrowed; a context you build with `createAPIContext` and pass to `executor.execute(op, input, context)` may still omit the signal, and a handler annotated with the plain `APIContext` is still accepted.
+
 ```typescript
 const exportReport = defineOperation({
   name: "reports.export",
@@ -341,7 +344,7 @@ At most `MAX_INTERCEPTORS` interceptors per executor, and each `next()` may be a
 
 ## Context
 
-`APIContext` carries the request id, an optional `AbortSignal`, caller state, and typed key/value slots. Keys carry their own identity, so two keys created with the same name never collide:
+`APIContext` carries the request id, an optional `AbortSignal` (always present on the handler's `APIHandlerContext`), caller state, and typed key/value slots. Keys carry their own identity, so two keys created with the same name never collide:
 
 ```typescript
 const FeatureFlagsKey = createContextKey<readonly string[]>("featureFlags");

package/dist/api/executor/executor.deadline.d.ts

@@ -1,4 +1,5 @@
 import type { APIContext } from "../context/context.type.js";
+import type { APIHandlerContext } from "../handler/handler.type.js";
 import type { APIError } from "../errors/index.js";
 /**
  * Error for an execution cancelled by the caller's `AbortSignal`.
@@ -19,7 +20,7 @@ export declare function abortedError(operationName: string): APIError;
  * is visible to the handler and vice versa, and any extra members of a
  * hand-rolled context are reachable through the prototype chain.
  */
-export declare function withContextSignal(context: APIContext, signal: AbortSignal): APIContext;
+export declare function withContextSignal(context: APIContext, signal: AbortSignal): APIHandlerContext;
 /**
  * Runs `run` under a deadline and the caller's abort signal.
  *

package/dist/api/handler/handler.type.d.ts

@@ -1,4 +1,16 @@
 import type { APIContext } from "../context/context.type.js";
+/**
+ * The context an operation handler receives.
+ *
+ * The caller's {@link APIContext} with a non-optional `signal`: the
+ * executor always derives one, which aborts when the operation's deadline
+ * elapses or the caller's own signal aborts, even when the caller passed
+ * no signal. Contexts built by callers (`createAPIContext`,
+ * `executor.execute(op, input, context)`) may still omit it.
+ */
+export type APIHandlerContext<TState = unknown> = APIContext<TState> & {
+    readonly signal: AbortSignal;
+};
 /**
  * Handler for an API operation.
  *
@@ -8,8 +20,8 @@ import type { APIContext } from "../context/context.type.js";
  * validated value; without one, input is passed through as-is and the
  * handler must validate it itself.
  *
- * `context.signal` aborts when the operation's deadline elapses or the
- * caller aborts; pass it to anything cancellable.
+ * `context.signal` is always present. It aborts when the operation's
+ * deadline elapses or the caller aborts; pass it to anything cancellable.
  */
-export type APIHandler<TInput = unknown, TOutput = unknown> = (input: TInput, context: APIContext) => Promise<TOutput>;
+export type APIHandler<TInput = unknown, TOutput = unknown> = (input: TInput, context: APIHandlerContext) => Promise<TOutput>;
 //# sourceMappingURL=handler.type.d.ts.map

package/dist/index.d.ts

@@ -43,7 +43,7 @@ export { APIError, APIValidationError, APIAuthenticationError, APIAuthorizationE
 export { DEFAULT_OPERATION_TIMEOUT, MAX_OPERATION_TIMEOUT, MAX_INTERCEPTORS, MAX_VALIDATION_ISSUES, MAX_VALIDATION_ISSUE_LENGTH, MAX_OPERATION_NAME_LENGTH, MAX_REQUEST_ID_LENGTH, } from "./api/constants.js";
 export type { APIContext, APIContextKey, APITransportKind, } from "./api/context/context.type.js";
 export { createAPIContext, createContextKey, isValidRequestId, normalizeRequestId, RequestIdContextKey, CorrelationIdContextKey, TenantIdContextKey, UserIdContextKey, StartTimeContextKey, TransportContextKey, } from "./api/context/context.type.js";
-export type { APIHandler } from "./api/handler/handler.type.js";
+export type { APIHandler, APIHandlerContext, } from "./api/handler/handler.type.js";
 export type { AnyAPIOperation, APIOperation, APIOperationMetadata, DefineOperationOptions, } from "./api/operation/operation.type.js";
 export { defineOperation, resolveOperationTimeout, } from "./api/operation/operation.type.js";
 export type { APIInputSchema, DefineOperationWithSchemaOptions, InferAPISchemaOutput, } from "./api/operation/operationSchema.type.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/api",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Application-facing API layer for Zudojs — operation definitions, execution context, interceptors, and transport-agnostic contracts.",
   "license": "MIT",
   "author": {
@@ -27,13 +27,13 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "1.3.0",
-    "@zudojs/openapi": "1.5.0",
-    "@zudojs/queue": "1.4.1",
-    "@zudojs/rpc": "1.4.1",
-    "@zudojs/schema": "1.2.1",
-    "@zudojs/security": "1.3.1",
-    "@zudojs/serialization": "1.2.1",
+    "@zudojs/errors": "1.3.2",
+    "@zudojs/openapi": "1.5.2",
+    "@zudojs/queue": "1.5.1",
+    "@zudojs/rpc": "1.4.3",
+    "@zudojs/schema": "1.2.3",
+    "@zudojs/security": "1.3.3",
+    "@zudojs/serialization": "1.2.3",
     "@zudojs/types": "1.2.0"
   },
   "devDependencies": {