@webpieces/core-util 0.4.806 → 0.4.807

package/src/mcp/DtoSchema.d.ts

@@ -1,64 +1,31 @@
-import 'reflect-metadata';
-export type DtoClass = abstract new (...args: any[]) => unknown;
-/** The element type of an array or the value type of a map; TypeScript erases both at runtime. */
-export type DtoElementType = 'string' | 'number' | 'integer' | 'boolean' | DtoClass;
-/** Runtime values accepted at the DTO validation boundary. */
-export type DtoValue = object | string | number | boolean | null;
-/** Additive field metadata; the scalar/object type itself comes from `design:type`. */
-export declare class WpDtoFieldOptions {
-    readonly description: string;
-    /** Required/optional is explicit because TypeScript erases `?` at runtime. */
-    readonly required: boolean;
-    /** Required for arrays because TypeScript erases their element type. */
-    readonly arrayItems?: DtoElementType | undefined;
-    /** A reflected Number is otherwise emitted as JSON Schema `number`. */
-    readonly integer: boolean;
-    readonly minimum?: number | undefined;
-    readonly maximum?: number | undefined;
-    readonly enumValues?: readonly [string, ...string[]] | undefined;
-    /** MCP 2026 SEP-2243 header mirrored as `Mcp-Param-{name}`. */
-    readonly mcpHeader?: WpMcpHeader | undefined;
-    constructor(description: string, 
-    /** Required/optional is explicit because TypeScript erases `?` at runtime. */
-    required: boolean, 
-    /** Required for arrays because TypeScript erases their element type. */
-    arrayItems?: DtoElementType | undefined, 
-    /** A reflected Number is otherwise emitted as JSON Schema `number`. */
-    integer?: boolean, minimum?: number | undefined, maximum?: number | undefined, enumValues?: readonly [string, ...string[]] | undefined, 
-    /** MCP 2026 SEP-2243 header mirrored as `Mcp-Param-{name}`. */
-    mcpHeader?: WpMcpHeader | undefined);
-}
 /**
- * Names the `x-mcp-header` a primitive tool parameter is mirrored into (`Mcp-Param-{name}`). A class,
- * not a bare string, so the 8th `WpDtoFieldOptions` argument can never be mistaken for a map value
- * type (maps use `WpDtoMapFieldOptions`).
+ * The JSON Schema subset webpieces publishes on its API boundaries, and the ONE runtime validator of
+ * it.
+ *
+ * ## Nothing here reads reflect-metadata any more
+ *
+ * Until #984 this file also carried `@WpDto`, `@WpDtoField`, `WpDtoFieldOptions`,
+ * `WpDtoMapFieldOptions`, `WpMcpHeader`, `@WpResponseDto` and `DtoSchemaBuilder` — a second, runtime
+ * spelling of facts the TypeScript compiler already holds. #983 measured the two against each other
+ * and found the compiler reproduces every one of those arguments byte for byte, so they are deleted
+ * rather than deprecated (`.claude/rules/no-backwards-compat.md`): a schema is now BUILT at build
+ * time from the source by `@webpieces/api-doc-model`, and the runtime is HANDED the result.
+ *
+ * What survives is the schema itself, a builder for the boundaries that construct one by hand, and a
+ * validator that reads the schema instead of a decorator.
  */
-export declare class WpMcpHeader {
-    readonly name: string;
-    constructor(name: string);
-}
+/** Runtime values accepted at the DTO validation boundary. */
+export type DtoValue = object | string | number | boolean | null;
 /**
- * Field metadata for a typed map such as `Record<string, string>` or `Record<string, SomeDto>`.
- * Keys are open strings; every VALUE must match `mapValues`. The value type is explicit for the same
- * reason `arrayItems` is: TypeScript erases it, and a `Record` reflects as plain `Object`.
+ * One JSON Schema `type`. `null` is a member because NULLABLE is expressed as `["string", "null"]`,
+ * which is how JSON Schema says "present, and may hold null" — a different wire document from an
+ * ABSENT property, and one the reflect-metadata runtime could neither see nor write down.
  */
-export declare class WpDtoMapFieldOptions {
-    readonly description: string;
-    /** Required/optional is explicit because TypeScript erases `?` at runtime. */
-    readonly required: boolean;
-    readonly mapValues: DtoElementType;
-    constructor(description: string, 
-    /** Required/optional is explicit because TypeScript erases `?` at runtime. */
-    required: boolean, mapValues: DtoElementType);
-}
-export declare class WpDtoFieldMetadata {
-    readonly propertyKey: string;
-    readonly options: WpDtoFieldOptions | WpDtoMapFieldOptions;
-    constructor(propertyKey: string, options: WpDtoFieldOptions | WpDtoMapFieldOptions);
-}
+export type ApiJsonSchemaType = 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'null';
 /** The JSON Schema subset emitted for Webpieces API DTOs. */
 export declare class ApiJsonSchema {
-    type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array';
+    /** One type, or `[T, "null"]` for a nullable field. */
+    type?: ApiJsonSchemaType | readonly ApiJsonSchemaType[];
     description?: string;
     properties?: Record<string, ApiJsonSchema>;
     required?: string[];
@@ -70,7 +37,42 @@ export declare class ApiJsonSchema {
     maximum?: number;
     /** MCP 2026 SEP-2243 schema extension consumed by the official SDK. */
     'x-mcp-header'?: string;
-    constructor(type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array');
+    constructor(type?: ApiJsonSchemaType | readonly ApiJsonSchemaType[]);
+    /**
+     * The non-`null` member of the type, which is the one that decides how a value is checked.
+     *
+     * These three are STATIC and not instance methods on purpose: an instance method would put a
+     * function on the structural type, and this class is handed straight to the MCP SDK, whose
+     * parameter types are index-signature JSON objects that a class carrying methods no longer
+     * satisfies. It stays a data-only structure (`CLAUDE.md` §1) and the helpers live beside it.
+     */
+    static baseTypeOf(schema: ApiJsonSchema): ApiJsonSchemaType | undefined;
+    /** True when the schema was widened with `"null"`, i.e. the property may hold `null`. */
+    static allowsNull(schema: ApiJsonSchema): boolean;
+    /**
+     * The one closure gate for an object schema. Closed means no key can carry an unspecified value:
+     * either extra keys are forbidden (`additionalProperties: false`) or every extra key's value is
+     * typed (`additionalProperties: <schema>`, a typed map). A missing or `true` value is open.
+     * Use this instead of `schema.additionalProperties === false`, which rejects typed maps.
+     */
+    static isClosed(schema: ApiJsonSchema): boolean;
+}
+/**
+ * Builds the CLOSED object schema a hand-written runtime boundary validates against — `@WpStream`'s
+ * two event schemas are the whole of its client list today.
+ *
+ * It exists because the alternative spellings are both worse: a decorator that re-states the field
+ * types the compiler already knows is exactly what #984 deleted, and a bare object literal is what
+ * `CLAUDE.md` §3 forbids. A generated schema never comes through here — it is read from the build's
+ * own artifact.
+ */
+export declare class ObjectSchemaBuilder {
+    private readonly schema;
+    private readonly requiredNames;
+    constructor();
+    required(name: string, type: ApiJsonSchema): this;
+    optional(name: string, type: ApiJsonSchema): this;
+    build(): ApiJsonSchema;
 }
 /** A validation result safe to show to an API caller/model. */
 export declare class DtoValidationFailure {
@@ -81,35 +83,20 @@ export declare class DtoValidationFailure {
     /** JSON path of the offending value, e.g. `$.address.city`. */
     field: string, message: string);
 }
-/** Marks a request/response class as a schema-bearing DTO, including intentionally empty DTOs. */
-export declare function WpDto(): ClassDecorator;
-/** Adds documentation and runtime-only shape facts to a DTO property. */
-export declare function WpDtoField(options: WpDtoFieldOptions | WpDtoMapFieldOptions): PropertyDecorator;
-/** Declares an async API method's response DTO because reflection sees Promise, not its generic. */
-export declare function WpResponseDto(responseDto: () => DtoClass): MethodDecorator;
-/** Builds and validates the same DTO schema used for MCP input and structured output. */
-export declare class DtoSchemaBuilder {
-    requestClassOf(apiClass: Function, methodName: string): DtoClass;
-    responseClassOf(apiClass: Function, methodName: string): DtoClass;
-    /**
-     * The one closure gate for an object schema. Closed means no key can carry an unspecified value:
-     * either extra keys are forbidden (`additionalProperties: false`) or every extra key's value is
-     * typed (`additionalProperties: <schema>`, a typed map). A missing or `true` value is open.
-     * Use this instead of `schema.additionalProperties === false`, which rejects typed maps.
-     */
-    isClosedSchema(schema: ApiJsonSchema): boolean;
-    build(dtoClass: DtoClass): ApiJsonSchema;
-    validate(dtoClass: DtoClass, value: DtoValue): DtoValidationFailure | undefined;
-    private buildAt;
-    private fieldSchema;
-    private validateOptions;
-    private itemSchema;
-    private validateMcpHeaders;
+/**
+ * Validates a value against an {@link ApiJsonSchema} — the ONE runtime narrowing boundary for MCP
+ * tool arguments, MCP structured output and typed stream events.
+ *
+ * It reads the SCHEMA, which is the same object the build published to agents, so a document that
+ * says a field is required and a server that accepts it missing cannot disagree. The predecessor
+ * walked reflect-metadata instead, which meant the published document and the accepted request were
+ * derived from two different declarations.
+ */
+export declare class ApiJsonSchemaValidator {
+    validate(schema: ApiJsonSchema, value: DtoValue): DtoValidationFailure | undefined;
     private validateAt;
-    private validateField;
+    private validateObject;
     private validateArray;
-    private validateMap;
-    private validateElement;
-    private fields;
-    private requireDto;
+    private validateString;
+    private validateNumber;
 }