webspresso 0.0.21 → 0.0.22

package/core/orm/schema-helpers.js

@@ -51,6 +51,250 @@ function getColumnMeta(schema) {
   return decodeColumnMeta(schema.description);
 }
 
+/**
+ * SchemaBuilder - Chainable wrapper for Zod schemas with validation and UI metadata
+ * @class
+ */
+class SchemaBuilder {
+  /**
+   * @param {import('zod').ZodTypeAny} schema - Base Zod schema
+   * @param {import('./types').ColumnMeta} baseMeta - Base column metadata
+   * @param {typeof import('zod').z} z - Zod instance
+   */
+  constructor(schema, baseMeta, z) {
+    this._schema = schema;
+    this._baseMeta = { ...baseMeta };
+    this._validations = {};
+    this._ui = {};
+    this._z = z;
+    this._finalized = false;
+  }
+
+  /**
+   * Proxy all Zod validation methods
+   */
+  min(value) {
+    this._validations.min = value;
+    if (typeof this._schema.min === 'function') {
+      this._schema = this._schema.min(value);
+    }
+    return this;
+  }
+
+  max(value) {
+    this._validations.max = value;
+    if (typeof this._schema.max === 'function') {
+      this._schema = this._schema.max(value);
+    }
+    return this;
+  }
+
+  length(value) {
+    this._validations.length = value;
+    if (typeof this._schema.length === 'function') {
+      this._schema = this._schema.length(value);
+    }
+    return this;
+  }
+
+  minLength(value) {
+    this._validations.minLength = value;
+    if (typeof this._schema.min === 'function') {
+      this._schema = this._schema.min(value);
+    }
+    return this;
+  }
+
+  maxLength(value) {
+    this._validations.maxLength = value;
+    if (typeof this._schema.max === 'function') {
+      this._schema = this._schema.max(value);
+    }
+    return this;
+  }
+
+  email() {
+    this._validations.email = true;
+    if (typeof this._schema.email === 'function') {
+      this._schema = this._schema.email();
+    }
+    return this;
+  }
+
+  url() {
+    this._validations.url = true;
+    if (typeof this._schema.url === 'function') {
+      this._schema = this._schema.url();
+    }
+    return this;
+  }
+
+  pattern(regex) {
+    const patternStr = regex instanceof RegExp ? regex.source : regex;
+    this._validations.pattern = patternStr;
+    if (typeof this._schema.regex === 'function') {
+      this._schema = this._schema.regex(regex);
+    }
+    return this;
+  }
+
+  includes(str) {
+    this._validations.includes = str;
+    if (typeof this._schema.includes === 'function') {
+      this._schema = this._schema.includes(str);
+    }
+    return this;
+  }
+
+  startsWith(str) {
+    this._validations.startsWith = str;
+    if (typeof this._schema.startsWith === 'function') {
+      this._schema = this._schema.startsWith(str);
+    }
+    return this;
+  }
+
+  endsWith(str) {
+    this._validations.endsWith = str;
+    if (typeof this._schema.endsWith === 'function') {
+      this._schema = this._schema.endsWith(str);
+    }
+    return this;
+  }
+
+  positive() {
+    this._validations.positive = true;
+    if (typeof this._schema.positive === 'function') {
+      this._schema = this._schema.positive();
+    }
+    return this;
+  }
+
+  negative() {
+    this._validations.negative = true;
+    if (typeof this._schema.negative === 'function') {
+      this._schema = this._schema.negative();
+    }
+    return this;
+  }
+
+  int() {
+    this._validations.int = true;
+    if (typeof this._schema.int === 'function') {
+      this._schema = this._schema.int();
+    }
+    return this;
+  }
+
+  step(value) {
+    this._validations.step = value;
+    // Zod doesn't have step, but we store it for UI
+    return this;
+  }
+
+  nonempty() {
+    this._validations.nonempty = true;
+    if (typeof this._schema.min === 'function') {
+      this._schema = this._schema.min(1);
+    } else if (typeof this._schema.length === 'function') {
+      this._schema = this._schema.min(1);
+    }
+    return this;
+  }
+
+  nullable() {
+    this._baseMeta.nullable = true;
+    if (this._schema.nullable) {
+      this._schema = this._schema.nullable();
+    }
+    return this;
+  }
+
+  optional() {
+    if (this._schema.optional) {
+      this._schema = this._schema.optional();
+    }
+    return this;
+  }
+
+  /**
+   * Configure UI metadata
+   * @param {import('./types').UIMeta} options - UI configuration options
+   * @returns {SchemaBuilder}
+   */
+  config(options) {
+    if (options.label !== undefined) this._ui.label = options.label;
+    if (options.placeholder !== undefined) this._ui.placeholder = options.placeholder;
+    if (options.hint !== undefined) this._ui.hint = options.hint;
+    if (options.inputType !== undefined) this._ui.inputType = options.inputType;
+    if (options.hidden !== undefined) this._ui.hidden = options.hidden;
+    if (options.readonly !== undefined) this._ui.readonly = options.readonly;
+    if (options.width !== undefined) this._ui.width = options.width;
+    if (options.rows !== undefined) this._ui.rows = options.rows;
+    return this;
+  }
+
+  /**
+   * Finalize the schema and return Zod schema with metadata
+   * @returns {import('zod').ZodTypeAny}
+   */
+  _finalize() {
+    if (this._finalized) {
+      return this._schema;
+    }
+
+    // Merge validations and UI into base metadata
+    const finalMeta = {
+      ...this._baseMeta,
+      ...(Object.keys(this._validations).length > 0 && { validations: this._validations }),
+      ...(Object.keys(this._ui).length > 0 && { ui: this._ui }),
+    };
+
+    // Apply metadata to schema
+    this._schema = this._schema.describe(encodeColumnMeta(finalMeta));
+    this._finalized = true;
+    return this._schema;
+  }
+
+  /**
+   * Proxy unknown methods to underlying Zod schema
+   */
+  _proxyMethod(name, args) {
+    if (typeof this._schema[name] === 'function') {
+      this._schema = this._schema[name](...args);
+      return this;
+    }
+    throw new Error(`Method ${name} is not available on this schema type`);
+  }
+}
+
+// Proxy handler for unknown methods
+const handler = {
+  get(target, prop) {
+    if (prop in target) {
+      return target[prop];
+    }
+    // Proxy unknown methods to Zod schema
+    if (typeof target._schema[prop] === 'function') {
+      return function(...args) {
+        return target._proxyMethod(prop, args);
+      };
+    }
+    return target._schema[prop];
+  },
+};
+
+/**
+ * Create a proxied SchemaBuilder instance
+ * @param {import('zod').ZodTypeAny} schema - Base Zod schema
+ * @param {import('./types').ColumnMeta} baseMeta - Base column metadata
+ * @param {typeof import('zod').z} z - Zod instance
+ * @returns {SchemaBuilder}
+ */
+function createSchemaBuilder(schema, baseMeta, z) {
+  return new Proxy(new SchemaBuilder(schema, baseMeta, z), handler);
+}
+
 /**
  * Create schema helpers bound to a Zod instance
  * @param {typeof import('zod').z} z - Zod instance
@@ -70,45 +314,55 @@ function createSchemaHelpers(z) {
   const helpers = {
     /**
      * Create a Zod object schema with database metadata
-     * @param {Object} shape - Object shape with zdb fields
+     * Automatically finalizes SchemaBuilder instances in the shape
+     * @param {Object} shape - Object shape with zdb fields (can be SchemaBuilder instances)
      * @returns {import('zod').ZodObject}
      */
     schema(shape) {
-      return z.object(shape);
+      const finalizedShape = {};
+      for (const [key, value] of Object.entries(shape)) {
+        // If it's a SchemaBuilder, finalize it
+        if (value && typeof value._finalize === 'function') {
+          finalizedShape[key] = value._finalize();
+        } else {
+          finalizedShape[key] = value;
+        }
+      }
+      return z.object(finalizedShape);
     },
     /**
      * Primary key column (bigint, auto-increment)
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
-     * @returns {import('zod').ZodNumber}
+     * @returns {SchemaBuilder}
      */
     id(options = {}) {
       const schema = z.number().int().positive().optional();
-      return withMeta(schema, {
+      return createSchemaBuilder(schema, {
         type: 'bigint',
         primary: true,
         autoIncrement: true,
         ...options,
-      });
+      }, z);
     },
 
     /**
      * UUID primary key column
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
-     * @returns {import('zod').ZodString}
+     * @returns {SchemaBuilder}
      */
     uuid(options = {}) {
       const schema = z.string().uuid().optional();
-      return withMeta(schema, {
+      return createSchemaBuilder(schema, {
         type: 'uuid',
         primary: true,
         ...options,
-      });
+      }, z);
     },
 
     /**
      * String column (varchar)
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
-     * @returns {import('zod').ZodString}
+     * @returns {SchemaBuilder}
      */
     string(options = {}) {
       const { maxLength = 255, nullable = false, ...rest } = options;
@@ -116,18 +370,18 @@ function createSchemaHelpers(z) {
       if (nullable) {
         schema = schema.nullable().optional();
       }
-      return withMeta(schema, {
+      return createSchemaBuilder(schema, {
         type: 'string',
         maxLength,
         nullable,
         ...rest,
-      });
+      }, z);
     },
 
     /**
      * Text column (unlimited length)
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
-     * @returns {import('zod').ZodString}
+     * @returns {SchemaBuilder}
      */
     text(options = {}) {
       const { nullable = false, ...rest } = options;
@@ -135,17 +389,17 @@ function createSchemaHelpers(z) {
       if (nullable) {
         schema = schema.nullable().optional();
       }
-      return withMeta(schema, {
+      return createSchemaBuilder(schema, {
         type: 'text',
         nullable,
         ...rest,
-      });
+      }, z);
     },
 
     /**
      * Integer column
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
-     * @returns {import('zod').ZodNumber}
+     * @returns {SchemaBuilder}
      */
     integer(options = {}) {
       const { nullable = false, ...rest } = options;
@@ -153,17 +407,17 @@ function createSchemaHelpers(z) {
       if (nullable) {
         schema = schema.nullable().optional();
       }
-      return withMeta(schema, {
+      return createSchemaBuilder(schema, {
         type: 'integer',
         nullable,
         ...rest,
-      });
+      }, z);
     },
 
     /**
      * Big integer column
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
-     * @returns {import('zod').ZodNumber}
+     * @returns {SchemaBuilder}
      */
     bigint(options = {}) {
       const { nullable = false, ...rest } = options;
@@ -171,17 +425,17 @@ function createSchemaHelpers(z) {
       if (nullable) {
         schema = schema.nullable().optional();
       }
-      return withMeta(schema, {
+      return createSchemaBuilder(schema, {
         type: 'bigint',
         nullable,
         ...rest,
-      });
+      }, z);
     },
 
     /**
      * Float column
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
-     * @returns {import('zod').ZodNumber}
+     * @returns {SchemaBuilder}
      */
     float(options = {}) {
       const { nullable = false, ...rest } = options;
@@ -189,17 +443,17 @@ function createSchemaHelpers(z) {
       if (nullable) {
         schema = schema.nullable().optional();
       }
-      return withMeta(schema, {
+      return createSchemaBuilder(schema, {
         type: 'float',
         nullable,
         ...rest,
-      });
+      }, z);
     },
 
     /**
      * Decimal column
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
-     * @returns {import('zod').ZodNumber}
+     * @returns {SchemaBuilder}
      */
     decimal(options = {}) {
       const { precision = 10, scale = 2, nullable = false, ...rest } = options;
@@ -207,19 +461,19 @@ function createSchemaHelpers(z) {
       if (nullable) {
         schema = schema.nullable().optional();
       }
-      return withMeta(schema, {
+      return createSchemaBuilder(schema, {
         type: 'decimal',
         precision,
         scale,
         nullable,
         ...rest,
-      });
+      }, z);
     },
 
     /**
      * Boolean column
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
-     * @returns {import('zod').ZodBoolean}
+     * @returns {SchemaBuilder}
      */
     boolean(options = {}) {
       const { nullable = false, default: defaultValue, ...rest } = options;
@@ -230,18 +484,18 @@ function createSchemaHelpers(z) {
       if (nullable) {
         schema = schema.nullable().optional();
       }
-      return withMeta(schema, {
+      return createSchemaBuilder(schema, {
         type: 'boolean',
         nullable,
         default: defaultValue,
         ...rest,
-      });
+      }, z);
     },
 
     /**
      * Date column (date only, no time)
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
-     * @returns {import('zod').ZodDate}
+     * @returns {SchemaBuilder}
      */
     date(options = {}) {
       const { nullable = false, ...rest } = options;
@@ -249,17 +503,17 @@ function createSchemaHelpers(z) {
       if (nullable) {
         schema = schema.nullable().optional();
       }
-      return withMeta(schema, {
+      return createSchemaBuilder(schema, {
         type: 'date',
         nullable,
         ...rest,
-      });
+      }, z);
     },
 
     /**
      * Datetime column
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
-     * @returns {import('zod').ZodDate}
+     * @returns {SchemaBuilder}
      */
     datetime(options = {}) {
       const { nullable = false, ...rest } = options;
@@ -267,17 +521,17 @@ function createSchemaHelpers(z) {
       if (nullable) {
         schema = schema.nullable().optional();
       }
-      return withMeta(schema, {
+      return createSchemaBuilder(schema, {
         type: 'datetime',
         nullable,
         ...rest,
-      });
+      }, z);
     },
 
     /**
      * Timestamp column (with optional auto behavior)
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
-     * @returns {import('zod').ZodDate}
+     * @returns {SchemaBuilder}
      */
     timestamp(options = {}) {
       const { nullable = false, auto, ...rest } = options;
@@ -286,18 +540,18 @@ function createSchemaHelpers(z) {
       if (nullable || auto) {
         schema = schema.nullable().optional();
       }
-      return withMeta(schema, {
+      return createSchemaBuilder(schema, {
         type: 'timestamp',
         nullable: nullable || !!auto,
         auto,
         ...rest,
-      });
+      }, z);
     },
 
     /**
      * JSON column
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
-     * @returns {import('zod').ZodUnknown}
+     * @returns {SchemaBuilder}
      */
     json(options = {}) {
       const { nullable = false, ...rest } = options;
@@ -305,18 +559,18 @@ function createSchemaHelpers(z) {
       if (nullable) {
         schema = schema.nullable().optional();
       }
-      return withMeta(schema, {
+      return createSchemaBuilder(schema, {
         type: 'json',
         nullable,
         ...rest,
-      });
+      }, z);
     },
 
     /**
      * Array column (stored as JSON in database)
      * @param {import('zod').ZodTypeAny} [itemSchema] - Schema for array items (default: z.any())
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
-     * @returns {import('zod').ZodArray}
+     * @returns {SchemaBuilder}
      */
     array(itemSchema, options = {}) {
       // If first argument is options object (backward compatibility)
@@ -333,18 +587,18 @@ function createSchemaHelpers(z) {
         schema = schema.nullable().optional();
       }
       
-      return withMeta(schema, {
+      return createSchemaBuilder(schema, {
         type: 'array',
         nullable,
         ...rest,
-      });
+      }, z);
     },
 
     /**
      * Enum column
      * @param {string[]} values - Allowed enum values
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
-     * @returns {import('zod').ZodEnum}
+     * @returns {SchemaBuilder}
      */
     enum(values, options = {}) {
       const { nullable = false, default: defaultValue, ...rest } = options;
@@ -355,20 +609,20 @@ function createSchemaHelpers(z) {
       if (nullable) {
         schema = schema.nullable().optional();
       }
-      return withMeta(schema, {
+      return createSchemaBuilder(schema, {
         type: 'enum',
         enumValues: values,
         nullable,
         default: defaultValue,
         ...rest,
-      });
+      }, z);
     },
 
     /**
      * Foreign key column (references another table)
      * @param {string} references - Referenced table name
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
-     * @returns {import('zod').ZodNumber}
+     * @returns {SchemaBuilder}
      */
     foreignKey(references, options = {}) {
       const { referenceColumn = 'id', nullable = false, ...rest } = options;
@@ -376,20 +630,20 @@ function createSchemaHelpers(z) {
       if (nullable) {
         schema = schema.nullable().optional();
       }
-      return withMeta(schema, {
+      return createSchemaBuilder(schema, {
         type: 'bigint',
         references,
         referenceColumn,
         nullable,
         ...rest,
-      });
+      }, z);
     },
 
     /**
      * UUID foreign key column
      * @param {string} references - Referenced table name
      * @param {Partial<import('./types').ColumnMeta>} [options={}]
-     * @returns {import('zod').ZodString}
+     * @returns {SchemaBuilder}
      */
     foreignUuid(references, options = {}) {
       const { referenceColumn = 'id', nullable = false, ...rest } = options;
@@ -397,13 +651,13 @@ function createSchemaHelpers(z) {
       if (nullable) {
         schema = schema.nullable().optional();
       }
-      return withMeta(schema, {
+      return createSchemaBuilder(schema, {
         type: 'uuid',
         references,
         referenceColumn,
         nullable,
         ...rest,
-      });
+      }, z);
     },
   };
 

package/core/orm/types.js

@@ -12,6 +12,38 @@
  * @typedef {'id'|'string'|'text'|'integer'|'bigint'|'float'|'decimal'|'boolean'|'date'|'datetime'|'timestamp'|'json'|'array'|'enum'|'uuid'} ColumnType
  */
 
+/**
+ * @typedef {Object} ValidationMeta
+ * @property {number} [min] - Minimum value/length
+ * @property {number} [max] - Maximum value/length
+ * @property {number} [minLength] - Minimum length (for strings/arrays)
+ * @property {number} [maxLength] - Maximum length (for strings/arrays)
+ * @property {number} [length] - Exact length
+ * @property {string} [pattern] - Regex pattern (as string)
+ * @property {boolean} [email] - Must be valid email
+ * @property {boolean} [url] - Must be valid URL
+ * @property {boolean} [positive] - Must be positive number
+ * @property {boolean} [negative] - Must be negative number
+ * @property {boolean} [int] - Must be integer
+ * @property {number} [step] - Step value for numbers
+ * @property {boolean} [nonempty] - Cannot be empty
+ * @property {string} [includes] - String must include this
+ * @property {string} [startsWith] - String must start with this
+ * @property {string} [endsWith] - String must end with this
+ */
+
+/**
+ * @typedef {Object} UIMeta
+ * @property {string} [label] - Form label text
+ * @property {string} [placeholder] - Input placeholder
+ * @property {string} [hint] - Help text shown below input
+ * @property {string} [inputType] - HTML input type (email, tel, url, currency, etc.)
+ * @property {boolean} [hidden] - Hide field in forms
+ * @property {boolean} [readonly] - Make field read-only
+ * @property {string} [width] - Input width (half, third, full)
+ * @property {number} [rows] - Number of rows for textarea
+ */
+
 /**
  * @typedef {Object} ColumnMeta
  * @property {ColumnType} type - Database column type
@@ -28,6 +60,8 @@
  * @property {string} [references] - Referenced table for foreign keys
  * @property {string} [referenceColumn='id'] - Referenced column name
  * @property {'create'|'update'} [auto] - Auto-set on create or update (for timestamps)
+ * @property {ValidationMeta} [validations] - Validation rules
+ * @property {UIMeta} [ui] - UI metadata for admin panel
  */
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "bin": {