@beignet/core/dist/openapi/schema-introspector.d.ts

Core framework primitives for Beignet

export type SchemaIO = "input" | "output";
type ConvertedSchemaObject = Record<string, unknown>;
/**
 * Context passed to an OpenAPI schema converter.
 */
export type SchemaConverterContext = {
    /**
     * Whether the schema is documenting request input or response output.
     */
    io: SchemaIO;
    /**
     * Component name hint Beignet will use when registering the converted schema.
     */
    nameHint: string;
};
/**
 * Converts a validation schema into an OpenAPI-compatible JSON Schema object.
 */
export interface SchemaConverter {
    /**
     * Human-readable converter name used in diagnostics.
     */
    name: string;
    /**
     * Return true when this converter owns the schema value.
     */
    canConvert(schema: unknown): boolean;
    /**
     * Convert the schema into an OpenAPI-compatible JSON Schema object.
     */
    toJSONSchema(schema: unknown, context: SchemaConverterContext): ConvertedSchemaObject;
}
/**
 * Schema introspection adapter.
 *
 * Abstracts the details of reading metadata from a schema library (e.g. Zod)
 * so that the OpenAPI generator is not directly coupled to `_def` internals.
 *
 * A default Zod implementation is provided via `createZodIntrospector()`.
 * To support a different schema library, implement this interface.
 */
export interface SchemaIntrospector {
    /**
     * Extract the shape (field name → field schema) from an object schema.
     * Returns undefined if the schema is not an object type or cannot be inspected.
     */
    getShape(schema: unknown): Record<string, unknown> | undefined;
    /**
     * Extract the user-supplied `.describe()` string from a schema.
     */
    getDescription(schema: unknown): string | undefined;
    /**
     * Return true if the schema represents an optional wrapper.
     */
    isOptional(schema: unknown): boolean;
    /**
     * If the schema is an optional wrapper, return the inner (unwrapped) schema.
     * Otherwise return the original schema unchanged.
     */
    unwrapOptional(schema: unknown): unknown;
}
/**
 * Create the default schema converter for Zod schemas.
 */
export declare function createZodSchemaConverter(): SchemaConverter;
/**
 * Create a schema introspector for Zod schemas.
 *
 * This accesses Zod's internal `_def` property, which is a common pattern in
 * Zod ecosystem libraries but may break with major Zod updates. Each helper
 * gracefully returns a safe default if the structure is unexpected.
 */
export declare function createZodIntrospector(): SchemaIntrospector;
export {};
//# sourceMappingURL=schema-introspector.d.ts.map