@vinkius-core/mcp-fusion 2.9.0 → 2.12.0

package/dist/core/builder/FluentSchemaHelpers.d.ts

@@ -0,0 +1,237 @@
+/**
+ * FluentSchemaHelpers — Chainable Parameter Declarations
+ *
+ * Provides `f.string()`, `f.number()`, `f.boolean()`, `f.enum()`, `f.array()`
+ * that build ParamDescriptors via fluent method chaining.
+ *
+ * These are syntax sugar over the existing `ParamDescriptors` system.
+ * At build time, `.toDescriptor()` produces the same JSON descriptor
+ * that `convertParamsToZod()` already knows how to convert.
+ *
+ * @example
+ * ```typescript
+ * const f = initFusion<AppContext>();
+ *
+ * f.query('users.list')
+ *   .input({
+ *     limit:  f.number().min(1).max(100).default(10).describe('Max results'),
+ *     status: f.enum('active', 'inactive').optional(),
+ *     name:   f.string().min(3).example('Alice').describe('Search by name'),
+ *   })
+ *   .resolve(async ({ input, ctx }) => { ... });
+ * ```
+ *
+ * @module
+ */
+import type { ParamDef, StringParamDef, NumberParamDef, BooleanParamDef, EnumParamDef, ArrayParamDef } from './ParamDescriptors.js';
+/**
+ * Symbol used to detect fluent schema helpers at runtime.
+ * @internal
+ */
+export declare const FLUENT_DESCRIPTOR: unique symbol;
+/**
+ * Base interface for all fluent descriptors.
+ * @internal
+ */
+export interface FluentDescriptor {
+    readonly [FLUENT_DESCRIPTOR]: true;
+    /** Convert the fluent descriptor to a plain ParamDef for ParamDescriptors. */
+    toDescriptor(): ParamDef;
+}
+/**
+ * Type guard: is this value a FluentDescriptor?
+ * @internal
+ */
+export declare function isFluentDescriptor(value: unknown): value is FluentDescriptor;
+/**
+ * Infer the TypeScript type from a single fluent descriptor or ParamDef.
+ * @internal
+ */
+type InferSingleFluent<T> = T extends FluentString ? string : T extends FluentNumber ? number : T extends FluentBoolean ? boolean : T extends FluentEnum<infer V> ? V : T extends FluentArray ? (T extends {
+    _itemType: 'string';
+} ? string[] : T extends {
+    _itemType: 'number';
+} ? number[] : T extends {
+    _itemType: 'boolean';
+} ? boolean[] : unknown[]) : T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : T extends {
+    type: 'string';
+} ? string : T extends {
+    type: 'number';
+} ? number : T extends {
+    type: 'boolean';
+} ? boolean : T extends {
+    enum: readonly (infer V)[];
+} ? V : T extends {
+    array: 'string';
+} ? string[] : T extends {
+    array: 'number';
+} ? number[] : T extends {
+    array: 'boolean';
+} ? boolean[] : unknown;
+/**
+ * Check if a fluent/param value is optional.
+ * @internal
+ */
+type IsFieldOptional<T> = T extends {
+    _optional: true;
+} ? true : T extends {
+    optional: true;
+} ? true : false;
+/** Required keys from a FluentParamsMap */
+type FluentRequiredKeys<T extends Record<string, unknown>> = {
+    [K in keyof T]: IsFieldOptional<T[K]> extends true ? never : K;
+}[keyof T];
+/** Optional keys from a FluentParamsMap */
+type FluentOptionalKeys<T extends Record<string, unknown>> = {
+    [K in keyof T]: IsFieldOptional<T[K]> extends true ? K : never;
+}[keyof T];
+/**
+ * Infer the full TypeScript type from a FluentParamsMap.
+ *
+ * Required params become required properties, optional params become
+ * optional properties with `| undefined`.
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   limit: f.number().min(1).max(100),           // required: number
+ *   status: f.enum('active', 'inactive').optional(), // optional: 'active' | 'inactive'
+ * };
+ * type T = InferFluentParams<typeof schema>;
+ * // { limit: number; status?: 'active' | 'inactive' }
+ * ```
+ */
+export type InferFluentParams<T extends Record<string, unknown>> = {
+    [K in FluentRequiredKeys<T>]: InferSingleFluent<T[K]>;
+} & {
+    [K in FluentOptionalKeys<T>]?: InferSingleFluent<T[K]>;
+};
+export declare class FluentString implements FluentDescriptor {
+    readonly [FLUENT_DESCRIPTOR]: true;
+    private _desc?;
+    /** @internal */ _optional: boolean;
+    private _min?;
+    private _max?;
+    private _regex?;
+    private _default?;
+    private _examples?;
+    /** Set minimum string length */
+    min(n: number): this;
+    /** Set maximum string length */
+    max(n: number): this;
+    /** Set regex validation pattern */
+    regex(pattern: string): this;
+    /** Mark as optional */
+    optional(): FluentString & {
+        _optional: true;
+    };
+    /** Set human-readable description */
+    describe(text: string): this;
+    /** Set default value (appended to description for LLM) */
+    default(value: string): this;
+    /** Add a single LLM few-shot example (AI-First DX) */
+    example(value: string): this;
+    /** Set multiple LLM few-shot examples */
+    examples(...values: string[]): this;
+    toDescriptor(): StringParamDef;
+}
+export declare class FluentNumber implements FluentDescriptor {
+    readonly [FLUENT_DESCRIPTOR]: true;
+    private _desc?;
+    /** @internal */ _optional: boolean;
+    private _min?;
+    private _max?;
+    private _int;
+    private _default?;
+    private _examples?;
+    /** Set minimum value */
+    min(n: number): this;
+    /** Set maximum value */
+    max(n: number): this;
+    /** Restrict to integers */
+    int(): this;
+    /** Mark as optional */
+    optional(): FluentNumber & {
+        _optional: true;
+    };
+    /** Set human-readable description */
+    describe(text: string): this;
+    /** Set default value (appended to description for LLM) */
+    default(value: number): this;
+    /** Add a single LLM few-shot example (AI-First DX) */
+    example(value: number): this;
+    /** Set multiple LLM few-shot examples */
+    examples(...values: number[]): this;
+    toDescriptor(): NumberParamDef;
+}
+export declare class FluentBoolean implements FluentDescriptor {
+    readonly [FLUENT_DESCRIPTOR]: true;
+    private _desc?;
+    /** @internal */ _optional: boolean;
+    private _default?;
+    /** Mark as optional */
+    optional(): FluentBoolean & {
+        _optional: true;
+    };
+    /** Set human-readable description */
+    describe(text: string): this;
+    /** Set default value (appended to description for LLM) */
+    default(value: boolean): this;
+    toDescriptor(): BooleanParamDef;
+}
+export declare class FluentEnum<V extends string = string> implements FluentDescriptor {
+    readonly [FLUENT_DESCRIPTOR]: true;
+    private _desc?;
+    /** @internal */ _optional: boolean;
+    private _examples?;
+    private _default?;
+    private readonly _values;
+    constructor(...values: [V, ...V[]]);
+    /** Mark as optional */
+    optional(): FluentEnum<V> & {
+        _optional: true;
+    };
+    /** Set human-readable description */
+    describe(text: string): this;
+    /** Set default value (appended to description for LLM) */
+    default(value: V): this;
+    /** Add a single LLM few-shot example (AI-First DX) */
+    example(value: V): this;
+    /** Set multiple LLM few-shot examples */
+    examples(...values: V[]): this;
+    toDescriptor(): EnumParamDef<V>;
+}
+type PrimitiveType = 'string' | 'number' | 'boolean';
+export declare class FluentArray implements FluentDescriptor {
+    readonly [FLUENT_DESCRIPTOR]: true;
+    private _desc?;
+    /** @internal */ _optional: boolean;
+    private _min?;
+    private _max?;
+    /** @internal */ readonly _itemType: PrimitiveType;
+    constructor(itemType: PrimitiveType);
+    /** Set minimum array length */
+    min(n: number): this;
+    /** Set maximum array length */
+    max(n: number): this;
+    /** Mark as optional */
+    optional(): FluentArray & {
+        _optional: true;
+    };
+    /** Set human-readable description */
+    describe(text: string): this;
+    toDescriptor(): ArrayParamDef;
+}
+/**
+ * A map where values can be either classic ParamDef or FluentDescriptor.
+ * The FluentToolBuilder resolves these to ParamDef at build time.
+ */
+export type FluentParamsMap = Record<string, ParamDef | FluentDescriptor>;
+/**
+ * Resolve a FluentParamsMap to a plain ParamsMap by calling .toDescriptor()
+ * on any FluentDescriptor values.
+ * @internal
+ */
+export declare function resolveFluentParams(input: FluentParamsMap): Record<string, ParamDef>;
+export {};
+//# sourceMappingURL=FluentSchemaHelpers.d.ts.map

package/dist/core/builder/FluentSchemaHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FluentSchemaHelpers.d.ts","sourceRoot":"","sources":["../../../src/core/builder/FluentSchemaHelpers.ts"],"names":[],"mappings":"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"}

package/dist/core/builder/FluentSchemaHelpers.js

@@ -0,0 +1,227 @@
+// ── Sentinel for fluent descriptor detection ──────────────
+/**
+ * Symbol used to detect fluent schema helpers at runtime.
+ * @internal
+ */
+export const FLUENT_DESCRIPTOR = Symbol.for('mcp-fusion.fluent-descriptor');
+/**
+ * Type guard: is this value a FluentDescriptor?
+ * @internal
+ */
+export function isFluentDescriptor(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        FLUENT_DESCRIPTOR in value &&
+        value[FLUENT_DESCRIPTOR] === true);
+}
+// ── String Helper ────────────────────────────────────────
+export class FluentString {
+    [FLUENT_DESCRIPTOR] = true;
+    _desc;
+    /** @internal */ _optional = false;
+    _min;
+    _max;
+    _regex;
+    _default;
+    _examples;
+    /** Set minimum string length */
+    min(n) { this._min = n; return this; }
+    /** Set maximum string length */
+    max(n) { this._max = n; return this; }
+    /** Set regex validation pattern */
+    regex(pattern) { this._regex = pattern; return this; }
+    /** Mark as optional */
+    optional() {
+        this._optional = true;
+        return this;
+    }
+    /** Set human-readable description */
+    describe(text) { this._desc = text; return this; }
+    /** Set default value (appended to description for LLM) */
+    default(value) { this._default = value; return this; }
+    /** Add a single LLM few-shot example (AI-First DX) */
+    example(value) {
+        if (!this._examples)
+            this._examples = [];
+        this._examples.push(value);
+        return this;
+    }
+    /** Set multiple LLM few-shot examples */
+    examples(...values) { this._examples = values; return this; }
+    toDescriptor() {
+        const desc = this._default !== undefined
+            ? (this._desc ? `${this._desc} (default: '${this._default}')` : `(default: '${this._default}')`)
+            : this._desc;
+        return {
+            type: 'string',
+            ...(desc && { description: desc }),
+            ...(this._optional && { optional: true }),
+            ...(this._min !== undefined && { min: this._min }),
+            ...(this._max !== undefined && { max: this._max }),
+            ...(this._regex !== undefined && { regex: this._regex }),
+            ...(this._examples && { examples: this._examples }),
+        };
+    }
+}
+// ── Number Helper ────────────────────────────────────────
+export class FluentNumber {
+    [FLUENT_DESCRIPTOR] = true;
+    _desc;
+    /** @internal */ _optional = false;
+    _min;
+    _max;
+    _int = false;
+    _default;
+    _examples;
+    /** Set minimum value */
+    min(n) { this._min = n; return this; }
+    /** Set maximum value */
+    max(n) { this._max = n; return this; }
+    /** Restrict to integers */
+    int() { this._int = true; return this; }
+    /** Mark as optional */
+    optional() {
+        this._optional = true;
+        return this;
+    }
+    /** Set human-readable description */
+    describe(text) { this._desc = text; return this; }
+    /** Set default value (appended to description for LLM) */
+    default(value) { this._default = value; return this; }
+    /** Add a single LLM few-shot example (AI-First DX) */
+    example(value) {
+        if (!this._examples)
+            this._examples = [];
+        this._examples.push(value);
+        return this;
+    }
+    /** Set multiple LLM few-shot examples */
+    examples(...values) { this._examples = values; return this; }
+    toDescriptor() {
+        const desc = this._default !== undefined
+            ? (this._desc ? `${this._desc} (default: ${this._default})` : `(default: ${this._default})`)
+            : this._desc;
+        return {
+            type: 'number',
+            ...(desc && { description: desc }),
+            ...(this._optional && { optional: true }),
+            ...(this._min !== undefined && { min: this._min }),
+            ...(this._max !== undefined && { max: this._max }),
+            ...(this._int && { int: true }),
+            ...(this._examples && { examples: this._examples }),
+        };
+    }
+}
+// ── Boolean Helper ───────────────────────────────────────
+export class FluentBoolean {
+    [FLUENT_DESCRIPTOR] = true;
+    _desc;
+    /** @internal */ _optional = false;
+    _default;
+    /** Mark as optional */
+    optional() {
+        this._optional = true;
+        return this;
+    }
+    /** Set human-readable description */
+    describe(text) { this._desc = text; return this; }
+    /** Set default value (appended to description for LLM) */
+    default(value) { this._default = value; return this; }
+    toDescriptor() {
+        const desc = this._default !== undefined
+            ? (this._desc ? `${this._desc} (default: ${this._default})` : `(default: ${this._default})`)
+            : this._desc;
+        return {
+            type: 'boolean',
+            ...(desc && { description: desc }),
+            ...(this._optional && { optional: true }),
+        };
+    }
+}
+// ── Enum Helper ──────────────────────────────────────────
+export class FluentEnum {
+    [FLUENT_DESCRIPTOR] = true;
+    _desc;
+    /** @internal */ _optional = false;
+    _examples;
+    _default;
+    _values;
+    constructor(...values) {
+        this._values = values;
+    }
+    /** Mark as optional */
+    optional() {
+        this._optional = true;
+        return this;
+    }
+    /** Set human-readable description */
+    describe(text) { this._desc = text; return this; }
+    /** Set default value (appended to description for LLM) */
+    default(value) { this._default = value; return this; }
+    /** Add a single LLM few-shot example (AI-First DX) */
+    example(value) {
+        if (!this._examples)
+            this._examples = [];
+        this._examples.push(value);
+        return this;
+    }
+    /** Set multiple LLM few-shot examples */
+    examples(...values) { this._examples = values; return this; }
+    toDescriptor() {
+        const desc = this._default !== undefined
+            ? (this._desc ? `${this._desc} (default: '${this._default}')` : `(default: '${this._default}')`)
+            : this._desc;
+        return {
+            enum: this._values,
+            ...(desc && { description: desc }),
+            ...(this._optional && { optional: true }),
+            ...(this._examples && { examples: this._examples }),
+        };
+    }
+}
+export class FluentArray {
+    [FLUENT_DESCRIPTOR] = true;
+    _desc;
+    /** @internal */ _optional = false;
+    _min;
+    _max;
+    /** @internal */ _itemType;
+    constructor(itemType) {
+        this._itemType = itemType;
+    }
+    /** Set minimum array length */
+    min(n) { this._min = n; return this; }
+    /** Set maximum array length */
+    max(n) { this._max = n; return this; }
+    /** Mark as optional */
+    optional() {
+        this._optional = true;
+        return this;
+    }
+    /** Set human-readable description */
+    describe(text) { this._desc = text; return this; }
+    toDescriptor() {
+        return {
+            array: this._itemType,
+            ...(this._desc && { description: this._desc }),
+            ...(this._optional && { optional: true }),
+            ...(this._min !== undefined && { min: this._min }),
+            ...(this._max !== undefined && { max: this._max }),
+        };
+    }
+}
+/**
+ * Resolve a FluentParamsMap to a plain ParamsMap by calling .toDescriptor()
+ * on any FluentDescriptor values.
+ * @internal
+ */
+export function resolveFluentParams(input) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(input)) {
+        resolved[key] = isFluentDescriptor(value)
+            ? value.toDescriptor()
+            : value;
+    }
+    return resolved;
+}
+//# sourceMappingURL=FluentSchemaHelpers.js.map

package/dist/core/builder/FluentSchemaHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FluentSchemaHelpers.js","sourceRoot":"","sources":["../../../src/core/builder/FluentSchemaHelpers.ts"],"names":[],"mappings":"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"}