@vurb/core 3.2.0

package/dist/presenter/typeHelpers.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Type Helpers — Zod-Backed Namespace for Presenter Schemas
+ *
+ * Inspired by ElysiaJS (`t.String`), Convex (`v.string()`), and
+ * Encore.ts (native TS types). Provides a compact namespace that
+ * eliminates the need to import Zod directly.
+ *
+ * Every `t.*` value IS a ZodType — zero abstraction leakage.
+ * Developers who need advanced Zod features can use `t.zod` escape hatch
+ * or mix `t.*` with raw Zod schemas freely.
+ *
+ * @example
+ * ```typescript
+ * import { createPresenter, t, ui } from 'vurb';
+ *
+ * const InvoicePresenter = createPresenter('Invoice')
+ *     .schema({
+ *         id:           t.string,
+ *         amount_cents: t.number.describe('CENTS — divide by 100'),
+ *         status:       t.enum('draft', 'sent', 'paid', 'overdue'),
+ *         tags:         t.array(t.string),
+ *         metadata:     t.optional(t.record(t.string)),
+ *     });
+ * ```
+ *
+ * @module
+ */
+import { z, type ZodType, type ZodRawShape } from 'zod';
+/**
+ * Compact type namespace for Presenter schema definitions.
+ *
+ * Eliminates `import { z } from 'zod'` for 95% of use cases.
+ * Every value is a real ZodType — `.describe()`, `.optional()`,
+ * `.nullable()`, `.default()` all work natively.
+ *
+ * @example
+ * ```typescript
+ * .schema({
+ *     id:     t.string,
+ *     count:  t.number,
+ *     active: t.boolean,
+ *     role:   t.enum('admin', 'user', 'guest'),
+ *     tags:   t.array(t.string),
+ * })
+ * ```
+ */
+export declare const t: {
+    /** String type — equivalent to `z.string()` */
+    readonly string: z.ZodString;
+    /** Number type — equivalent to `z.number()` */
+    readonly number: z.ZodNumber;
+    /** Boolean type — equivalent to `z.boolean()` */
+    readonly boolean: z.ZodBoolean;
+    /** Date type — equivalent to `z.date()` */
+    readonly date: z.ZodDate;
+    /**
+     * Create an enum type from string literals.
+     *
+     * @param values - At least one enum value
+     * @returns A Zod enum schema
+     *
+     * @example
+     * ```typescript
+     * t.enum('active', 'archived')  // z.enum(['active', 'archived'])
+     * ```
+     */
+    readonly enum: <V extends string>(values_0: V, ...values: V[]) => z.ZodEnum<[V, ...V[]]>;
+    /**
+     * Create an array type.
+     *
+     * @param item - The schema for array items
+     * @returns A Zod array schema
+     *
+     * @example
+     * ```typescript
+     * t.array(t.string)       // z.array(z.string())
+     * t.array(t.number)       // z.array(z.number())
+     * ```
+     */
+    readonly array: <T extends ZodType>(item: T) => z.ZodArray<T, "many">;
+    /**
+     * Create a nested object type.
+     *
+     * @param shape - Object shape with ZodType values
+     * @returns A Zod object schema
+     *
+     * @example
+     * ```typescript
+     * t.object({ lat: t.number, lng: t.number })  // z.object({...})
+     * ```
+     */
+    readonly object: <T extends ZodRawShape>(shape: T) => z.ZodObject<T, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<T>, any> extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never, z.baseObjectInputType<T> extends infer T_2 ? { [k_1 in keyof T_2]: T_2[k_1]; } : never>;
+    /**
+     * Create a record (dictionary) type.
+     *
+     * @param valueType - Schema for record values
+     * @returns A Zod record schema
+     *
+     * @example
+     * ```typescript
+     * t.record(t.string)  // z.record(z.string())
+     * ```
+     */
+    readonly record: <T extends ZodType>(valueType: T) => z.ZodRecord<z.ZodString, T>;
+    /**
+     * Make a type optional.
+     *
+     * @param type - Any ZodType to make optional
+     * @returns An optional variant of the given type
+     *
+     * @example
+     * ```typescript
+     * t.optional(t.string)   // z.string().optional()
+     * t.optional(t.number)   // z.number().optional()
+     * ```
+     */
+    readonly optional: <T extends ZodType>(type: T) => z.ZodOptional<T>;
+    /**
+     * Make a type nullable.
+     *
+     * @param type - Any ZodType to make nullable
+     * @returns A nullable variant of the given type
+     *
+     * @example
+     * ```typescript
+     * t.nullable(t.string)   // z.string().nullable()
+     * ```
+     */
+    readonly nullable: <T extends ZodType>(type: T) => z.ZodNullable<T>;
+    /**
+     * Direct access to Zod for advanced use cases.
+     *
+     * Use when `t.*` helpers don't cover your needs:
+     * regex, transforms, refinements, unions, discriminated unions, etc.
+     *
+     * @example
+     * ```typescript
+     * .schema({
+     *     id:    t.string,
+     *     email: t.zod.string().email().min(5),  // Zod power features
+     *     role:  t.zod.union([t.zod.literal('admin'), t.zod.literal('user')]),
+     * })
+     * ```
+     */
+    readonly zod: typeof z;
+};
+//# sourceMappingURL=typeHelpers.d.ts.map

package/dist/presenter/typeHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeHelpers.d.ts","sourceRoot":"","sources":["../../src/presenter/typeHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,CAAC,EAAE,KAAK,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAIxD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,CAAC;IAGV,+CAA+C;;IAG/C,+CAA+C;;IAG/C,iDAAiD;;IAGjD,2CAA2C;;IAK3C;;;;;;;;;;OAUG;oBACI,CAAC,SAAS,MAAM;IAGvB;;;;;;;;;;;OAWG;qBACK,CAAC,SAAS,OAAO,QAAQ,CAAC;IAGlC;;;;;;;;;;OAUG;sBACM,CAAC,SAAS,WAAW,SAAS,CAAC;IAGxC;;;;;;;;;;OAUG;sBACM,CAAC,SAAS,OAAO,aAAa,CAAC;IAKxC;;;;;;;;;;;OAWG;wBACQ,CAAC,SAAS,OAAO,QAAQ,CAAC;IAGrC;;;;;;;;;;OAUG;wBACQ,CAAC,SAAS,OAAO,QAAQ,CAAC;IAKrC;;;;;;;;;;;;;;OAcG;;CAEG,CAAC"}

package/dist/presenter/typeHelpers.js

@@ -0,0 +1,152 @@
+/**
+ * Type Helpers — Zod-Backed Namespace for Presenter Schemas
+ *
+ * Inspired by ElysiaJS (`t.String`), Convex (`v.string()`), and
+ * Encore.ts (native TS types). Provides a compact namespace that
+ * eliminates the need to import Zod directly.
+ *
+ * Every `t.*` value IS a ZodType — zero abstraction leakage.
+ * Developers who need advanced Zod features can use `t.zod` escape hatch
+ * or mix `t.*` with raw Zod schemas freely.
+ *
+ * @example
+ * ```typescript
+ * import { createPresenter, t, ui } from 'vurb';
+ *
+ * const InvoicePresenter = createPresenter('Invoice')
+ *     .schema({
+ *         id:           t.string,
+ *         amount_cents: t.number.describe('CENTS — divide by 100'),
+ *         status:       t.enum('draft', 'sent', 'paid', 'overdue'),
+ *         tags:         t.array(t.string),
+ *         metadata:     t.optional(t.record(t.string)),
+ *     });
+ * ```
+ *
+ * @module
+ */
+import { z } from 'zod';
+// ── Type Helpers Namespace ─────────────────────────────────
+/**
+ * Compact type namespace for Presenter schema definitions.
+ *
+ * Eliminates `import { z } from 'zod'` for 95% of use cases.
+ * Every value is a real ZodType — `.describe()`, `.optional()`,
+ * `.nullable()`, `.default()` all work natively.
+ *
+ * @example
+ * ```typescript
+ * .schema({
+ *     id:     t.string,
+ *     count:  t.number,
+ *     active: t.boolean,
+ *     role:   t.enum('admin', 'user', 'guest'),
+ *     tags:   t.array(t.string),
+ * })
+ * ```
+ */
+export const t = {
+    // ── Primitives (singleton instances) ──────────────────
+    /** String type — equivalent to `z.string()` */
+    string: z.string(),
+    /** Number type — equivalent to `z.number()` */
+    number: z.number(),
+    /** Boolean type — equivalent to `z.boolean()` */
+    boolean: z.boolean(),
+    /** Date type — equivalent to `z.date()` */
+    date: z.date(),
+    // ── Composites (factory functions) ────────────────────
+    /**
+     * Create an enum type from string literals.
+     *
+     * @param values - At least one enum value
+     * @returns A Zod enum schema
+     *
+     * @example
+     * ```typescript
+     * t.enum('active', 'archived')  // z.enum(['active', 'archived'])
+     * ```
+     */
+    enum: (...values) => z.enum(values),
+    /**
+     * Create an array type.
+     *
+     * @param item - The schema for array items
+     * @returns A Zod array schema
+     *
+     * @example
+     * ```typescript
+     * t.array(t.string)       // z.array(z.string())
+     * t.array(t.number)       // z.array(z.number())
+     * ```
+     */
+    array: (item) => z.array(item),
+    /**
+     * Create a nested object type.
+     *
+     * @param shape - Object shape with ZodType values
+     * @returns A Zod object schema
+     *
+     * @example
+     * ```typescript
+     * t.object({ lat: t.number, lng: t.number })  // z.object({...})
+     * ```
+     */
+    object: (shape) => z.object(shape),
+    /**
+     * Create a record (dictionary) type.
+     *
+     * @param valueType - Schema for record values
+     * @returns A Zod record schema
+     *
+     * @example
+     * ```typescript
+     * t.record(t.string)  // z.record(z.string())
+     * ```
+     */
+    record: (valueType) => z.record(valueType),
+    // ── Modifiers (wrappers) ─────────────────────────────
+    /**
+     * Make a type optional.
+     *
+     * @param type - Any ZodType to make optional
+     * @returns An optional variant of the given type
+     *
+     * @example
+     * ```typescript
+     * t.optional(t.string)   // z.string().optional()
+     * t.optional(t.number)   // z.number().optional()
+     * ```
+     */
+    optional: (type) => type.optional(),
+    /**
+     * Make a type nullable.
+     *
+     * @param type - Any ZodType to make nullable
+     * @returns A nullable variant of the given type
+     *
+     * @example
+     * ```typescript
+     * t.nullable(t.string)   // z.string().nullable()
+     * ```
+     */
+    nullable: (type) => type.nullable(),
+    // ── Escape Hatch ─────────────────────────────────────
+    /**
+     * Direct access to Zod for advanced use cases.
+     *
+     * Use when `t.*` helpers don't cover your needs:
+     * regex, transforms, refinements, unions, discriminated unions, etc.
+     *
+     * @example
+     * ```typescript
+     * .schema({
+     *     id:    t.string,
+     *     email: t.zod.string().email().min(5),  // Zod power features
+     *     role:  t.zod.union([t.zod.literal('admin'), t.zod.literal('user')]),
+     * })
+     * ```
+     */
+    zod: z,
+};
+//# sourceMappingURL=typeHelpers.js.map

package/dist/presenter/typeHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeHelpers.js","sourceRoot":"","sources":["../../src/presenter/typeHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,CAAC,EAAkC,MAAM,KAAK,CAAC;AAExD,8DAA8D;AAE9D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,CAAC,GAAG;IACb,yDAAyD;IAEzD,+CAA+C;IAC/C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAElB,+CAA+C;IAC/C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAElB,iDAAiD;IACjD,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IAEpB,2CAA2C;IAC3C,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;IAEd,yDAAyD;IAEzD;;;;;;;;;;OAUG;IACH,IAAI,EAAE,CAAmB,GAAG,MAAmB,EAAE,EAAE,CAC/C,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;IAElB;;;;;;;;;;;OAWG;IACH,KAAK,EAAE,CAAoB,IAAO,EAAE,EAAE,CAClC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;IAEjB;;;;;;;;;;OAUG;IACH,MAAM,EAAE,CAAwB,KAAQ,EAAE,EAAE,CACxC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;IAEnB;;;;;;;;;;OAUG;IACH,MAAM,EAAE,CAAoB,SAAY,EAAE,EAAE,CACxC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC;IAEvB,wDAAwD;IAExD;;;;;;;;;;;OAWG;IACH,QAAQ,EAAE,CAAoB,IAAO,EAAE,EAAE,CACrC,IAAI,CAAC,QAAQ,EAAE;IAEnB;;;;;;;;;;OAUG;IACH,QAAQ,EAAE,CAAoB,IAAO,EAAE,EAAE,CACrC,IAAI,CAAC,QAAQ,EAAE;IAEnB,wDAAwD;IAExD;;;;;;;;;;;;;;OAcG;IACH,GAAG,EAAE,CAAC;CACA,CAAC"}

package/dist/presenter/ui.d.ts

@@ -0,0 +1,205 @@
+/**
+ * UI Block Helpers — Server-Side Rendering for AI Agents
+ *
+ * Deterministic helpers that wrap structured content into fenced
+ * code blocks (or raw markup) for LLM pass-through rendering.
+ *
+ * Today these produce `text` blocks with fenced syntax.
+ * If MCP adds native UI content types in the future, only
+ * the internal `fence()` wrapper needs to change — all Presenters
+ * and consumers stay intact.
+ *
+ * @example
+ * ```typescript
+ * import { ui } from 'vurb';
+ *
+ * ui.echarts({ title: { text: 'Burndown' }, series: [...] });
+ * ui.mermaid('graph TD; A-->B');
+ * ui.markdown('| Col | Val |');
+ * ui.table(['ID', 'Status'], [['INV-1', '✅ Paid']]);
+ * ui.list(['Deploy', 'Migrate', 'Verify']);
+ * ui.json({ key: 'value' });
+ * ui.summary('3 items found. 2 active, 1 archived.');
+ * ```
+ *
+ * @module
+ */
+/**
+ * A structured UI block produced by a Presenter's SSR layer.
+ *
+ * Each block carries a semantic `type` for future protocol
+ * evolution and the `content` string ready for MCP transport.
+ */
+export interface UiBlock {
+    /** Semantic type identifier (e.g. `'echarts'`, `'mermaid'`, `'markdown'`) */
+    readonly type: string;
+    /** Ready-to-transport content string */
+    readonly content: string;
+}
+/**
+ * Generate an ECharts UI block from a configuration object.
+ *
+ * The config is serialized with `JSON.stringify(config, null, 2)` for
+ * deterministic, hallucination-free chart rendering.
+ *
+ * @param config - A valid ECharts option object
+ * @returns A {@link UiBlock} with fenced `echarts` code block
+ *
+ * @example
+ * ```typescript
+ * ui.echarts({
+ *     title: { text: 'Sprint Burndown' },
+ *     xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed'] },
+ *     series: [{ type: 'line', data: [5, 3, 1] }]
+ * });
+ * ```
+ */
+declare function echarts(config: Record<string, unknown>): UiBlock;
+/**
+ * Generate a Mermaid diagram UI block.
+ *
+ * @param diagram - Raw Mermaid diagram syntax
+ * @returns A {@link UiBlock} with fenced `mermaid` code block
+ *
+ * @example
+ * ```typescript
+ * ui.mermaid('graph TD; A["Start"] --> B["Process"] --> C["End"]');
+ * ```
+ */
+declare function mermaid(diagram: string): UiBlock;
+/**
+ * Generate a raw Markdown UI block.
+ *
+ * Unlike other helpers, markdown content is **not** fenced —
+ * it's returned as-is for direct rendering.
+ *
+ * @param md - Raw Markdown string
+ * @returns A {@link UiBlock} with raw markdown content
+ *
+ * @example
+ * ```typescript
+ * ui.markdown('| Task | Status |\n|---|---|\n| Deploy | ✅ Done |');
+ * ```
+ */
+declare function markdown(md: string): UiBlock;
+/**
+ * Generate a generic fenced code block UI block.
+ *
+ * Fallback helper for structured content (logs, XML, raw JSON)
+ * that needs explicit language tagging.
+ *
+ * @param lang - Language identifier for syntax highlighting
+ * @param code - Code content
+ * @returns A {@link UiBlock} with fenced code block
+ *
+ * @example
+ * ```typescript
+ * ui.codeBlock('json', JSON.stringify(config, null, 2));
+ * ui.codeBlock('xml', '<root><item>value</item></root>');
+ * ```
+ */
+declare function codeBlock(lang: string, code: string): UiBlock;
+/**
+ * Generate a Markdown table UI block from headers and row data.
+ *
+ * The **#1 most common pattern** in data tools. Automatically
+ * generates a fully formatted markdown table with alignment
+ * separators — zero manual string concatenation needed.
+ *
+ * @param headers - Column header labels
+ * @param rows - Array of row arrays (each inner array = one row)
+ * @returns A {@link UiBlock} with formatted markdown table
+ *
+ * @example
+ * ```typescript
+ * ui.table(
+ *     ['Invoice', 'Amount', 'Status'],
+ *     [
+ *         ['INV-001', '$4,500.00', '✅ Paid'],
+ *         ['INV-002', '$1,200.00', '⚠️ Pending'],
+ *     ],
+ * );
+ * ```
+ */
+declare function table(headers: readonly string[], rows: readonly (readonly string[])[]): UiBlock;
+/**
+ * Generate a Markdown bullet list UI block.
+ *
+ * Perfect for action items, checklists, or enumerated results.
+ *
+ * @param items - Array of list items (strings)
+ * @returns A {@link UiBlock} with markdown list content
+ *
+ * @example
+ * ```typescript
+ * ui.list(['Deploy API server', 'Run database migrations', 'Verify health checks']);
+ * // → "- Deploy API server\n- Run database migrations\n- Verify health checks"
+ * ```
+ */
+declare function list(items: readonly string[]): UiBlock;
+/**
+ * Generate a fenced JSON code block UI block.
+ *
+ * Shorthand for `ui.codeBlock('json', JSON.stringify(data, null, 2))`.
+ * Most developers reach for this pattern constantly.
+ *
+ * @param data - Any JSON-serializable value
+ * @returns A {@link UiBlock} with fenced `json` code block
+ *
+ * @example
+ * ```typescript
+ * ui.json({ host: 'api.example.com', port: 3000, ssl: true });
+ * ```
+ */
+declare function json(data: unknown): UiBlock;
+/**
+ * Generate a summary UI block for collection overviews.
+ *
+ * Placed at the top of collection responses to give the LLM
+ * quick context about the dataset without parsing the full array.
+ *
+ * @param text - Human-readable summary of the collection
+ * @returns A {@link UiBlock} with summary content
+ *
+ * @example
+ * ```typescript
+ * ui.summary('3 invoices totaling $5,700.00. 2 paid, 1 pending.');
+ * ```
+ */
+declare function summary(text: string): UiBlock;
+/**
+ * UI block helpers for Server-Side Rendering (SSR) in Presenters.
+ *
+ * **Core helpers**: `echarts`, `mermaid`, `markdown`, `codeBlock`
+ * **DX helpers**: `table`, `list`, `json`, `summary`
+ *
+ * @example
+ * ```typescript
+ * import { ui } from 'vurb';
+ *
+ * // Quick table from arrays
+ * ui.table(['Name', 'Status'], [['Alice', 'Active'], ['Bob', 'Inactive']]);
+ *
+ * // Quick list
+ * ui.list(['Step 1: Deploy', 'Step 2: Verify']);
+ *
+ * // Quick JSON viewer
+ * ui.json({ config: { debug: true } });
+ *
+ * // Charts and diagrams
+ * ui.echarts(chartConfig);
+ * ui.mermaid('graph TD; A-->B');
+ * ```
+ */
+export declare const ui: {
+    readonly echarts: typeof echarts;
+    readonly mermaid: typeof mermaid;
+    readonly markdown: typeof markdown;
+    readonly codeBlock: typeof codeBlock;
+    readonly table: typeof table;
+    readonly list: typeof list;
+    readonly json: typeof json;
+    readonly summary: typeof summary;
+};
+export {};
+//# sourceMappingURL=ui.d.ts.map

package/dist/presenter/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../src/presenter/ui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACpB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC5B;AAkBD;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAS,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;GAUG;AACH,iBAAS,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzC;AAED;;;;;;;;;;;;;GAaG;AACH,iBAAS,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAErC;AAED;;;;;;;;;;;;;;;GAeG;AACH,iBAAS,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,iBAAS,KAAK,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,GAAG,OAAO,CAKxF;AAED;;;;;;;;;;;;;GAaG;AACH,iBAAS,IAAI,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAE/C;AAED;;;;;;;;;;;;;GAaG;AACH,iBAAS,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAEpC;AAED;;;;;;;;;;;;;GAaG;AACH,iBAAS,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtC;AAID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,EAAE;;;;;;;;;CAKL,CAAC"}