@zudojs/api 1.0.1 → 1.1.0

package/README.md

@@ -2,6 +2,12 @@
 
 Higher-level API layer — operation definitions, execution context, interceptors, and a transport-agnostic executor. Sits above `@zudojs/http` and `@zudojs/cqrs`.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-api](https://zudojs.oyinlola.site/docs/packages-api) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-api.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## When to use
 
 Import this when you need:
@@ -78,7 +84,7 @@ import {
 // 1. Define the operation. The handler is positional: (input, context).
 const getUser = defineOperation<{ id: string }, { id: string; name: string }>({
   name: "users.get",
-  input: GetUserSchema, // any Standard Schema (Zod, Valibot, ArkType, …)
+  input: GetUserSchema, // @zudojs/schema, or any Standard Schema (Zod, Valibot, …)
   output: UserSchema, // validated too — see "Output validation"
   timeout: 5_000,
   metadata: { tags: ["Users"] },
@@ -116,7 +122,25 @@ Results are frozen `{ ok: true, data }` / `{ ok: false, error }` objects — `ex
 
 ## Input validation
 
-When `operation.input` is a Standard Schema, the executor validates the input before the handler runs and passes the schema's *transformed* value to the handler. Failures return an `APIValidationError` (422).
+The executor accepts two kinds of schema for `input` and `output`, recognised structurally so the package depends on no validation library:
+
+- a `@zudojs/schema` schema, or any other schema with a `safeParse` method returning `{ success, data }` / `{ success: false, issues }` (Zod-style `error.issues` also works);
+- a [Standard Schema](https://standardschema.dev) (`"~standard".validate`): Zod, Valibot, ArkType, ….
+
+Anything else fails closed. `defineOperation` and `APIOperationRegistry.register` throw a `TypeError` when `input` or `output` is set to a value that is neither, and the executor answers a hand-rolled operation carrying one with an `APIInternalError` (500) without running the handler. A schema is never silently skipped. `isAPISchema(value)` reports whether a value would be accepted.
+
+```typescript
+import { schema } from "@zudojs/schema";
+
+const charge = defineOperation({
+  name: "payments.charge",
+  input: schema.object({ id: schema.string().uuid(), amount: schema.number().min(1) }),
+  output: schema.object({ ok: schema.boolean() }), // strips unknown keys
+  handler: async (input) => ({ ok: true }),
+});
+```
+
+The executor validates the input before the handler runs and passes the schema's *transformed* value to the handler. Failures return an `APIValidationError` (422).
 
 Schema issue messages routinely interpolate the value that failed, so by default the executor does **not** copy them into the client-facing error: each issue becomes `"<path>: invalid"` (e.g. `"user.email: invalid"`), naming where validation failed without echoing what was submitted. The list is capped at `MAX_VALIDATION_ISSUES` entries with a trailing `"… and N more issue(s) omitted."` marker.
 
@@ -128,7 +152,7 @@ new APIExecutor({ exposeValidationMessages: true, maxValidationIssues: 10 });
 
 ## Output validation
 
-When `operation.output` is a Standard Schema, the handler's return value is validated too, and the validated (possibly stripped or transformed) value becomes `result.data`. A mismatch is a server bug, so it fails with an `APIInternalError` (500, `expose: false`) naming only the failing paths.
+When `operation.output` is set, the handler's return value is validated too, and the validated (possibly stripped or transformed) value becomes `result.data`. A mismatch is a server bug, so it fails with an `APIInternalError` (500, `expose: false`) naming only the failing paths.
 
 ## Timeouts
 

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

@@ -53,8 +53,10 @@ export interface APIExecutorOptions {
  * Executes an API operation through its interceptor pipeline.
  *
  * Enforces the operation timeout, honors the context AbortSignal, and
- * validates input and output when the operation's `input` / `output` is a
- * Standard Schema.
+ * validates input and output against the operation's `input` / `output`
+ * schema (a Standard Schema or a `safeParse` schema such as
+ * `@zudojs/schema`). A declared schema of any other kind fails closed
+ * with an `APIInternalError`; it is never skipped.
  */
 export declare class APIExecutor {
     private readonly interceptors;
@@ -67,8 +69,7 @@ export declare class APIExecutor {
     execute<TInput = unknown, TOutput = unknown>(operation: APIOperation<TInput, TOutput>, input: TInput, context: APIContext): Promise<APIResult<TOutput>>;
     /**
      * Invokes the operation handler under its timeout and abort signal, and
-     * validates the handler's output when `operation.output` is a Standard
-     * Schema.
+     * validates the handler's output against `operation.output`.
      */
     private invokeHandler;
     /**

package/dist/api/executor/executor.core.js

@@ -1,6 +1,7 @@
 import { apiFailure, apiSuccess } from "../result/apiResult.type.js";
 import { resolveOperationTimeout } from "../operation/operation.type.js";
 import { APIError, APIInternalError, APITimeoutError, APIValidationError, createAPIError, ErrorCode, isAPIError, } from "../errors/index.js";
+import { validateWithSchema } from "../schema/index.js";
 import { MAX_INTERCEPTORS, MAX_VALIDATION_ISSUES, MAX_VALIDATION_ISSUE_LENGTH, } from "../constants.js";
 /**
  * Error normalizer for converting unknown errors into APIError instances.
@@ -45,27 +46,14 @@ function describeValueType(value) {
     }
     return typeof value;
 }
-function isStandardSchema(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        typeof value["~standard"]
-            ?.validate === "function");
-}
-/**
- * A schema result counts as a failure only when it carries at least one
- * issue. Some adapters always populate `issues` and return an empty array
- * on success; treating that as a failure produces a 422 with an empty
- * issue list and no way to learn what was wrong.
- */
-function hasIssues(result) {
-    return Array.isArray(result.issues) && result.issues.length > 0;
-}
 /**
  * Executes an API operation through its interceptor pipeline.
  *
  * Enforces the operation timeout, honors the context AbortSignal, and
- * validates input and output when the operation's `input` / `output` is a
- * Standard Schema.
+ * validates input and output against the operation's `input` / `output`
+ * schema (a Standard Schema or a `safeParse` schema such as
+ * `@zudojs/schema`). A declared schema of any other kind fails closed
+ * with an `APIInternalError`; it is never skipped.
  */
 export class APIExecutor {
     interceptors;
@@ -97,10 +85,10 @@ export class APIExecutor {
             return apiFailure(abortedError(operation.name));
         }
         let effectiveInput = input;
-        if (isStandardSchema(operation.input)) {
+        if (operation.input !== undefined) {
             try {
-                const validation = await operation.input["~standard"].validate(input);
-                if (hasIssues(validation)) {
+                const validation = await validateWithSchema(operation.input, input);
+                if (!validation.ok) {
                     return apiFailure(new APIValidationError(`Invalid input for operation "${operation.name}".`, this.clientIssues(validation.issues)));
                 }
                 effectiveInput = validation.value;
@@ -127,8 +115,7 @@ export class APIExecutor {
     }
     /**
      * Invokes the operation handler under its timeout and abort signal, and
-     * validates the handler's output when `operation.output` is a Standard
-     * Schema.
+     * validates the handler's output against `operation.output`.
      */
     async invokeHandler(operation, input, context) {
         if (context.signal?.aborted) {
@@ -154,17 +141,17 @@ export class APIExecutor {
      * internal audit columns) that should not reach a client.
      */
     async validateOutput(operation, output) {
-        if (!isStandardSchema(operation.output)) {
+        if (operation.output === undefined) {
             return apiSuccess(output);
         }
         let validation;
         try {
-            validation = await operation.output["~standard"].validate(output);
+            validation = await validateWithSchema(operation.output, output);
         }
         catch (error) {
             return apiFailure(normalizeAPIError(error, operation.name));
         }
-        if (hasIssues(validation)) {
+        if (!validation.ok) {
             const paths = validation.issues
                 .slice(0, this.maxValidationIssues)
                 .map(formatIssuePath)

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

@@ -23,19 +23,21 @@ export interface APIOperationMetadata {
 export interface APIOperation<TInput = unknown, TOutput = unknown> {
     readonly name: string;
     /**
-     * Input schema. When this is a Standard Schema
-     * (https://standardschema.dev), the executor validates input against it
-     * before invoking the handler; other values are documentation-only.
+     * Input schema: a Standard Schema (https://standardschema.dev) or a
+     * `safeParse` schema such as `@zudojs/schema`. The executor validates
+     * input against it before invoking the handler. Any other non-`undefined`
+     * value is rejected by {@link defineOperation} and the registry, and
+     * fails closed in the executor.
      */
     readonly input?: unknown;
     /**
-     * Output schema. When this is a Standard Schema
-     * (https://standardschema.dev), the executor validates the handler's
-     * return value against it and returns the validated (possibly
-     * transformed) value as the result data; a handler returning the wrong
+     * Output schema: a Standard Schema or a `safeParse` schema such as
+     * `@zudojs/schema`. The executor validates the handler's return value
+     * against it and returns the validated (possibly transformed or
+     * stripped) value as the result data; a handler returning the wrong
      * shape fails with an `APIInternalError` (`expose: false`) rather than
-     * leaking through to the transport. Other values are
-     * documentation-only.
+     * leaking through to the transport. Any other non-`undefined` value is
+     * rejected, exactly like {@link APIOperation.input}.
      */
     readonly output?: unknown;
     readonly handler: APIHandler<TInput, TOutput>;
@@ -105,13 +107,16 @@ export declare function resolveOperationTimeout(source: {
  * `APIOperationRegistry.register`, since `APIOperation` is a bare
  * interface that callers can satisfy without `defineOperation`.
  *
- * @throws {TypeError} if `name` or `handler` has the wrong type.
+ * @throws {TypeError} if `name` or `handler` has the wrong type, or if
+ * `input` / `output` is set but is not a recognised schema.
  * @throws {RangeError} if `name` is empty, over-long, or contains
  * characters outside `[A-Za-z0-9._:/-]`.
  */
 export declare function assertValidOperationShape(operation: {
     readonly name?: unknown;
     readonly handler?: unknown;
+    readonly input?: unknown;
+    readonly output?: unknown;
 }): void;
 /**
  * Deeply freezes an operation's metadata so a registered operation cannot
@@ -125,7 +130,8 @@ export declare function freezeOperationMetadata(metadata: APIOperationMetadata |
  * unusable timeout fails here, at startup, rather than on the first
  * request that reaches the operation.
  *
- * @throws {TypeError} if `name` or `handler` has the wrong type.
+ * @throws {TypeError} if `name` or `handler` has the wrong type, or if
+ * `input` / `output` is set but is not a recognised schema.
  * @throws {RangeError} if `name` or a supplied `timeout` is out of range.
  */
 export declare function defineOperation<TInput = unknown, TOutput = unknown>(options: DefineOperationOptions<TInput, TOutput>): APIOperation<TInput, TOutput>;

package/dist/api/operation/operation.type.js

@@ -1,3 +1,4 @@
+import { assertAPISchema } from "../schema/index.js";
 import { DEFAULT_OPERATION_TIMEOUT, MAX_OPERATION_NAME_LENGTH, MAX_OPERATION_TIMEOUT, } from "../constants.js";
 const OPERATION_NAME_PATTERN = /^[A-Za-z0-9._:/-]+$/;
 /**
@@ -56,7 +57,8 @@ export function resolveOperationTimeout(source) {
  * `APIOperationRegistry.register`, since `APIOperation` is a bare
  * interface that callers can satisfy without `defineOperation`.
  *
- * @throws {TypeError} if `name` or `handler` has the wrong type.
+ * @throws {TypeError} if `name` or `handler` has the wrong type, or if
+ * `input` / `output` is set but is not a recognised schema.
  * @throws {RangeError} if `name` is empty, over-long, or contains
  * characters outside `[A-Za-z0-9._:/-]`.
  */
@@ -77,6 +79,8 @@ export function assertValidOperationShape(operation) {
     if (typeof handler !== "function") {
         throw new TypeError(`Operation "${name}" must have a handler function, received ${typeof handler}.`);
     }
+    assertAPISchema(operation.input, "input", name);
+    assertAPISchema(operation.output, "output", name);
 }
 /**
  * Deeply freezes an operation's metadata so a registered operation cannot
@@ -98,7 +102,8 @@ export function freezeOperationMetadata(metadata) {
  * unusable timeout fails here, at startup, rather than on the first
  * request that reaches the operation.
  *
- * @throws {TypeError} if `name` or `handler` has the wrong type.
+ * @throws {TypeError} if `name` or `handler` has the wrong type, or if
+ * `input` / `output` is set but is not a recognised schema.
  * @throws {RangeError} if `name` or a supplied `timeout` is out of range.
  */
 export function defineOperation(options) {

package/dist/api/registry/operationRegistry.core.d.ts

@@ -19,7 +19,7 @@ export declare class APIOperationRegistry {
      *
      * @throws {APIDuplicateOperationError} if an operation with the same name is already registered.
      * @throws {APIError} if the registry is frozen.
-     * @throws {TypeError | RangeError} if the operation's name or handler is invalid.
+     * @throws {TypeError | RangeError} if the operation's name, handler, or input/output schema is invalid.
      */
     register(operation: AnyAPIOperation): void;
     /**

package/dist/api/registry/operationRegistry.core.js

@@ -20,7 +20,7 @@ export class APIOperationRegistry {
      *
      * @throws {APIDuplicateOperationError} if an operation with the same name is already registered.
      * @throws {APIError} if the registry is frozen.
-     * @throws {TypeError | RangeError} if the operation's name or handler is invalid.
+     * @throws {TypeError | RangeError} if the operation's name, handler, or input/output schema is invalid.
      */
     register(operation) {
         if (this.frozen) {

package/dist/api/schema/apiSchema.adapter.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Schema recognition and validation for operation `input` / `output`.
+ *
+ * Two contracts are recognised structurally, so the package depends on no
+ * particular validation library:
+ *
+ * 1. Standard Schema (https://standardschema.dev): a `"~standard"` object
+ *    with a `validate` function (Zod, Valibot, ArkType, …).
+ * 2. A `safeParse` schema returning `{ success, data }` /
+ *    `{ success: false, issues }` (`@zudojs/schema`) or
+ *    `{ success: false, error: { issues } }` (Zod-style).
+ *
+ * Anything else is *unrecognised*. The executor fails closed on an
+ * unrecognised schema rather than treating it as documentation, because a
+ * schema that is silently skipped validates nothing.
+ */
+type IssuePathSegment = PropertyKey | {
+    readonly key: PropertyKey;
+};
+/** A validation issue normalised from either supported contract. */
+export interface APISchemaIssue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<IssuePathSegment>;
+}
+/** Normalised validation outcome. */
+export type APISchemaResult = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly issues: ReadonlyArray<APISchemaIssue>;
+};
+/**
+ * Whether `value` is a schema the executor can validate against.
+ *
+ * `undefined` (no schema declared) is not a schema; callers treat it as
+ * "nothing to validate" and must reject every other unrecognised value.
+ */
+export declare function isAPISchema(value: unknown): boolean;
+/**
+ * Throws when `schema` is declared but is not a recognised schema.
+ *
+ * @throws {TypeError} naming the operation and the offending field.
+ */
+export declare function assertAPISchema(schema: unknown, field: "input" | "output", operationName: string): void;
+/**
+ * Validates `value` against a recognised schema.
+ *
+ * Fails closed: an unrecognised schema, or a result in an unexpected
+ * shape, throws rather than letting the value through.
+ *
+ * @throws {TypeError} for an unrecognised schema or malformed result.
+ */
+export declare function validateWithSchema(schema: unknown, value: unknown): Promise<APISchemaResult>;
+export {};
+//# sourceMappingURL=apiSchema.adapter.d.ts.map

package/dist/api/schema/apiSchema.adapter.js

@@ -0,0 +1,109 @@
+/**
+ * Schema recognition and validation for operation `input` / `output`.
+ *
+ * Two contracts are recognised structurally, so the package depends on no
+ * particular validation library:
+ *
+ * 1. Standard Schema (https://standardschema.dev): a `"~standard"` object
+ *    with a `validate` function (Zod, Valibot, ArkType, …).
+ * 2. A `safeParse` schema returning `{ success, data }` /
+ *    `{ success: false, issues }` (`@zudojs/schema`) or
+ *    `{ success: false, error: { issues } }` (Zod-style).
+ *
+ * Anything else is *unrecognised*. The executor fails closed on an
+ * unrecognised schema rather than treating it as documentation, because a
+ * schema that is silently skipped validates nothing.
+ */
+function isStandardSchema(value) {
+    if (typeof value !== "object" && typeof value !== "function")
+        return false;
+    if (value === null)
+        return false;
+    const standard = value["~standard"];
+    return typeof standard?.validate === "function";
+}
+function isSafeParseSchema(value) {
+    if (typeof value !== "object" && typeof value !== "function")
+        return false;
+    if (value === null)
+        return false;
+    return typeof value.safeParse === "function";
+}
+/**
+ * Whether `value` is a schema the executor can validate against.
+ *
+ * `undefined` (no schema declared) is not a schema; callers treat it as
+ * "nothing to validate" and must reject every other unrecognised value.
+ */
+export function isAPISchema(value) {
+    return isStandardSchema(value) || isSafeParseSchema(value);
+}
+/**
+ * Throws when `schema` is declared but is not a recognised schema.
+ *
+ * @throws {TypeError} naming the operation and the offending field.
+ */
+export function assertAPISchema(schema, field, operationName) {
+    if (schema === undefined || isAPISchema(schema))
+        return;
+    throw new TypeError(`Operation "${operationName}" declares an ${field} schema that is neither a Standard Schema ("~standard".validate) nor a safeParse schema; refusing to run it unvalidated.`);
+}
+const MALFORMED = "Schema returned a result in an unrecognised shape.";
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function toIssues(raw) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return [{ message: "Validation failed without a recorded issue." }];
+    }
+    return raw.map((issue) => {
+        const record = isRecord(issue) ? issue : {};
+        const path = Array.isArray(record["path"])
+            ? record["path"]
+            : undefined;
+        const message = typeof record["message"] === "string" ? record["message"] : "invalid";
+        return path === undefined ? { message } : { message, path };
+    });
+}
+function fromStandard(result) {
+    if (!isRecord(result))
+        throw new TypeError(MALFORMED);
+    const issues = result["issues"];
+    if (Array.isArray(issues) && issues.length > 0) {
+        return { ok: false, issues: toIssues(issues) };
+    }
+    if (!("value" in result))
+        throw new TypeError(MALFORMED);
+    return { ok: true, value: result["value"] };
+}
+function fromSafeParse(result) {
+    if (!isRecord(result))
+        throw new TypeError(MALFORMED);
+    if (result["success"] === true) {
+        return { ok: true, value: result["data"] };
+    }
+    if (result["success"] === false) {
+        const error = result["error"];
+        const issues = result["issues"] ?? (isRecord(error) ? error["issues"] : undefined);
+        return { ok: false, issues: toIssues(issues) };
+    }
+    throw new TypeError(MALFORMED);
+}
+/**
+ * Validates `value` against a recognised schema.
+ *
+ * Fails closed: an unrecognised schema, or a result in an unexpected
+ * shape, throws rather than letting the value through.
+ *
+ * @throws {TypeError} for an unrecognised schema or malformed result.
+ */
+export async function validateWithSchema(schema, value) {
+    if (isStandardSchema(schema)) {
+        return fromStandard(await schema["~standard"].validate(value));
+    }
+    if (isSafeParseSchema(schema)) {
+        return fromSafeParse(await schema.safeParse(value));
+    }
+    throw new TypeError("Unrecognised schema: refusing to validate.");
+}
+//# sourceMappingURL=apiSchema.adapter.js.map

package/dist/api/schema/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @zudojs/api/schema
+ *
+ * Structural recognition of operation schemas (Standard Schema and
+ * `safeParse` schemas such as `@zudojs/schema`) and fail-closed validation.
+ */
+export { assertAPISchema, isAPISchema, validateWithSchema, } from "./apiSchema.adapter.js";
+export type { APISchemaIssue, APISchemaResult } from "./apiSchema.adapter.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/api/schema/index.js

@@ -0,0 +1,8 @@
+/**
+ * @zudojs/api/schema
+ *
+ * Structural recognition of operation schemas (Standard Schema and
+ * `safeParse` schemas such as `@zudojs/schema`) and fail-closed validation.
+ */
+export { assertAPISchema, isAPISchema, validateWithSchema, } from "./apiSchema.adapter.js";
+//# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -17,7 +17,7 @@
  *
  * const getUser = defineOperation({
  *   name: "users.get",
- *   input: GetUserSchema, // any Standard Schema (Zod, Valibot, ArkType, …)
+ *   input: GetUserSchema, // @zudojs/schema, or any Standard Schema (Zod, Valibot, …)
  *   output: UserSchema,
  *   handler: async (input, context) => userService.findById(input.id),
  * });
@@ -44,6 +44,8 @@ export { createAPIContext, createContextKey, isValidRequestId, normalizeRequestI
 export type { APIHandler } 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 { APISchemaIssue, APISchemaResult } from "./api/schema/index.js";
+export { isAPISchema } from "./api/schema/index.js";
 export { APIOperationRegistry } from "./api/registry/index.js";
 export type { APIInterceptor, APIExecutionContext, } from "./api/interceptors/interceptor.type.js";
 export { createNoopInterceptor } from "./api/interceptors/interceptor.type.js";

package/dist/index.js

@@ -17,7 +17,7 @@
  *
  * const getUser = defineOperation({
  *   name: "users.get",
- *   input: GetUserSchema, // any Standard Schema (Zod, Valibot, ArkType, …)
+ *   input: GetUserSchema, // @zudojs/schema, or any Standard Schema (Zod, Valibot, …)
  *   output: UserSchema,
  *   handler: async (input, context) => userService.findById(input.id),
  * });
@@ -40,6 +40,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 { createAPIContext, createContextKey, isValidRequestId, normalizeRequestId, RequestIdContextKey, CorrelationIdContextKey, TenantIdContextKey, UserIdContextKey, StartTimeContextKey, } from "./api/context/context.type.js";
 export { defineOperation, resolveOperationTimeout, } from "./api/operation/operation.type.js";
+export { isAPISchema } from "./api/schema/index.js";
 // Registry
 export { APIOperationRegistry } from "./api/registry/index.js";
 export { createNoopInterceptor } from "./api/interceptors/interceptor.type.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/api",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Application-facing API layer for Zudojs — operation definitions, execution context, interceptors, and transport-agnostic contracts.",
   "license": "MIT",
   "author": {
@@ -27,12 +27,10 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "1.0.1",
-    "@zudojs/constants": "1.0.1",
-    "@zudojs/types": "1.0.0",
-    "@zudojs/schema": "1.0.1"
+    "@zudojs/errors": "1.1.0"
   },
   "devDependencies": {
+    "@zudojs/schema": "1.1.0",
     "typescript": "7.0.2",
     "vitest": "^4.1.11"
   },