metal-orm 1.0.80 → 1.0.81

package/dist/index.cjs

@@ -96,6 +96,7 @@ __export(index_exports, {
   bitOr: () => bitOr,
   bitXor: () => bitXor,
   bootstrapEntities: () => bootstrapEntities,
+  buildFilterParameters: () => buildFilterParameters,
   caseWhen: () => caseWhen,
   cast: () => cast,
   cbrt: () => cbrt,
@@ -6950,26 +6951,33 @@ var SelectRelationFacet = class {
 };
 
 // src/openapi/type-mappers.ts
-var mapColumnType = (column) => {
+var mapColumnType = (column, options = {}) => {
+  const resolved = resolveColumnOptions(options);
   const sqlType = normalizeType(column.type);
   const baseSchema = mapSqlTypeToBaseSchema(sqlType, column);
   const schema = {
-    ...baseSchema,
-    description: column.comment,
-    nullable: !column.notNull && !column.primary
+    ...baseSchema
   };
-  if (column.args && sqlType === "varchar" || sqlType === "char") {
+  if (resolved.includeDescriptions && column.comment) {
+    schema.description = column.comment;
+  }
+  if (resolved.includeNullable) {
+    schema.nullable = !column.notNull && !column.primary;
+  }
+  if ((sqlType === "varchar" || sqlType === "char") && column.args) {
     schema.maxLength = column.args[0];
   }
-  if (column.args && sqlType === "decimal" || sqlType === "float") {
+  if ((sqlType === "decimal" || sqlType === "float") && column.args) {
     if (column.args.length >= 1) {
       schema.minimum = -(10 ** column.args[0]);
     }
   }
-  if (sqlType === "enum" && column.args && column.args.length > 0) {
+  if (!resolved.includeEnums) {
+    delete schema.enum;
+  } else if (sqlType === "enum" && column.args && column.args.length > 0) {
     schema.enum = column.args;
   }
-  if (column.default !== void 0) {
+  if (resolved.includeDefaults && column.default !== void 0) {
     schema.default = column.default;
   }
   return schema;
@@ -7085,6 +7093,13 @@ var inferTypeFromTsType = (tsType) => {
   }
   return "string";
 };
+var resolveColumnOptions = (options) => ({
+  includeDescriptions: options.includeDescriptions ?? false,
+  includeEnums: options.includeEnums ?? true,
+  includeExamples: options.includeExamples ?? false,
+  includeDefaults: options.includeDefaults ?? true,
+  includeNullable: options.includeNullable ?? true
+});
 var mapRelationType = (relationType) => {
   switch (relationType) {
     case "HAS_MANY":
@@ -7112,14 +7127,55 @@ var getTemporalFormat = (sqlType) => {
 };
 
 // src/openapi/schema-extractor.ts
+var DEFAULT_MAX_DEPTH = 5;
 var extractSchema = (table, plan, projectionNodes, options = {}) => {
-  const mode = options.mode ?? "full";
-  const context = {
-    visitedTables: /* @__PURE__ */ new Set(),
-    schemaCache: /* @__PURE__ */ new Map(),
-    depth: 0,
-    maxDepth: options.maxDepth ?? 5
+  const outputOptions = resolveOutputOptions(options);
+  const outputContext = createContext(outputOptions.maxDepth ?? DEFAULT_MAX_DEPTH);
+  const output = extractOutputSchema(table, plan, projectionNodes, outputContext, outputOptions);
+  const inputOptions = resolveInputOptions(options);
+  if (!inputOptions) {
+    return { output };
+  }
+  const inputContext = createContext(inputOptions.maxDepth ?? DEFAULT_MAX_DEPTH);
+  const input = extractInputSchema(table, inputContext, inputOptions);
+  return { output, input };
+};
+var resolveOutputOptions = (options) => ({
+  mode: options.mode ?? "full",
+  includeDescriptions: options.includeDescriptions,
+  includeEnums: options.includeEnums,
+  includeExamples: options.includeExamples,
+  includeDefaults: options.includeDefaults,
+  includeNullable: options.includeNullable,
+  maxDepth: options.maxDepth ?? DEFAULT_MAX_DEPTH
+});
+var resolveInputOptions = (options) => {
+  if (options.input === false) return void 0;
+  const input = options.input ?? {};
+  const mode = input.mode ?? "create";
+  return {
+    mode,
+    includeRelations: input.includeRelations ?? true,
+    relationMode: input.relationMode ?? "mixed",
+    includeDescriptions: input.includeDescriptions ?? options.includeDescriptions,
+    includeEnums: input.includeEnums ?? options.includeEnums,
+    includeExamples: input.includeExamples ?? options.includeExamples,
+    includeDefaults: input.includeDefaults ?? options.includeDefaults,
+    includeNullable: input.includeNullable ?? options.includeNullable,
+    maxDepth: input.maxDepth ?? options.maxDepth ?? DEFAULT_MAX_DEPTH,
+    omitReadOnly: input.omitReadOnly ?? true,
+    excludePrimaryKey: input.excludePrimaryKey ?? false,
+    requirePrimaryKey: input.requirePrimaryKey ?? mode === "update"
   };
+};
+var createContext = (maxDepth) => ({
+  visitedTables: /* @__PURE__ */ new Set(),
+  schemaCache: /* @__PURE__ */ new Map(),
+  depth: 0,
+  maxDepth
+});
+var extractOutputSchema = (table, plan, projectionNodes, context, options) => {
+  const mode = options.mode ?? "full";
   const hasComputedFields = projectionNodes && projectionNodes.some(
     (node) => node.type !== "Column"
   );
@@ -7131,9 +7187,97 @@ var extractSchema = (table, plan, projectionNodes, options = {}) => {
   }
   return extractFullTableSchema(table, context, options);
 };
+var extractInputSchema = (table, context, options) => {
+  const cacheKey = `${table.name}:${options.mode ?? "create"}`;
+  if (context.schemaCache.has(cacheKey)) {
+    return context.schemaCache.get(cacheKey);
+  }
+  if (context.visitedTables.has(cacheKey) && context.depth > 0) {
+    return buildCircularReferenceSchema(table.name, "input");
+  }
+  context.visitedTables.add(cacheKey);
+  const properties = {};
+  const required = [];
+  const primaryKey = findPrimaryKey(table);
+  for (const [columnName, column] of Object.entries(table.columns)) {
+    const isPrimary = columnName === primaryKey || column.primary;
+    if (options.excludePrimaryKey && isPrimary) continue;
+    if (options.omitReadOnly && isReadOnlyColumn(column)) continue;
+    properties[columnName] = mapColumnType(column, options);
+    if (options.mode === "create" && isRequiredForCreate(column)) {
+      required.push(columnName);
+    }
+    if (options.mode === "update" && options.requirePrimaryKey && isPrimary) {
+      required.push(columnName);
+    }
+  }
+  if (options.includeRelations && context.depth < context.maxDepth) {
+    for (const [relationName, relation] of Object.entries(table.relations)) {
+      properties[relationName] = extractInputRelationSchema(
+        relation,
+        { ...context, depth: context.depth + 1 },
+        options
+      );
+    }
+  }
+  const schema = {
+    type: "object",
+    properties,
+    required
+  };
+  context.schemaCache.set(cacheKey, schema);
+  return schema;
+};
+var isReadOnlyColumn = (column) => Boolean(column.autoIncrement || column.generated === "always");
+var isRequiredForCreate = (column) => {
+  if (isReadOnlyColumn(column)) return false;
+  if (column.default !== void 0) return false;
+  return Boolean(column.notNull || column.primary);
+};
+var buildPrimaryKeySchema = (table, options) => {
+  const primaryKey = findPrimaryKey(table);
+  const column = table.columns[primaryKey];
+  if (!column) {
+    return {
+      anyOf: [
+        { type: "string" },
+        { type: "number" },
+        { type: "integer" }
+      ]
+    };
+  }
+  return mapColumnType(column, options);
+};
+var extractInputRelationSchema = (relation, context, options) => {
+  const { type: relationType, isNullable } = mapRelationType(relation.type);
+  const relationMode = options.relationMode ?? "mixed";
+  const allowIds = relationMode !== "objects";
+  const allowObjects = relationMode !== "ids";
+  const variants = [];
+  if (allowIds) {
+    variants.push(buildPrimaryKeySchema(relation.target, options));
+  }
+  if (allowObjects) {
+    const targetSchema = extractInputSchema(relation.target, context, options);
+    variants.push(targetSchema);
+  }
+  const itemSchema = variants.length === 1 ? variants[0] : { anyOf: variants };
+  if (relationType === "array") {
+    return {
+      type: "array",
+      items: itemSchema,
+      nullable: isNullable
+    };
+  }
+  return {
+    ...itemSchema,
+    nullable: isNullable
+  };
+};
 var extractFromProjectionNodes = (table, projectionNodes, context, options) => {
   const properties = {};
   const required = [];
+  const includeDescriptions = Boolean(options.includeDescriptions);
   for (const node of projectionNodes) {
     if (!node || typeof node !== "object") continue;
     const projection = node;
@@ -7143,10 +7287,7 @@ var extractFromProjectionNodes = (table, projectionNodes, context, options) => {
       const columnNode4 = node;
       const column = table.columns[columnNode4.name];
       if (!column) continue;
-      const property = mapColumnType(column);
-      if (!property.description && options.includeDescriptions && column.comment) {
-        property.description = column.comment;
-      }
+      const property = mapColumnType(column, options);
       properties[propertyName] = property;
       if (column.notNull || column.primary) {
         required.push(propertyName);
@@ -7154,7 +7295,7 @@ var extractFromProjectionNodes = (table, projectionNodes, context, options) => {
     } else if (projection.type === "Function" || projection.type === "WindowFunction") {
       const fnNode = node;
       const functionName = fnNode.fn?.toUpperCase() ?? fnNode.name?.toUpperCase() ?? "";
-      const propertySchema = projection.type === "Function" ? mapFunctionNodeToSchema(functionName) : mapWindowFunctionToSchema(functionName);
+      const propertySchema = projection.type === "Function" ? mapFunctionNodeToSchema(functionName, includeDescriptions) : mapWindowFunctionToSchema(functionName, includeDescriptions);
       properties[propertyName] = propertySchema;
       const isCountFunction = functionName === "COUNT";
       const isWindowRankFunction = functionName === "ROW_NUMBER" || functionName === "RANK";
@@ -7164,23 +7305,29 @@ var extractFromProjectionNodes = (table, projectionNodes, context, options) => {
     } else if (projection.type === "CaseExpression") {
       const propertySchema = {
         type: "string",
-        description: "Computed CASE expression",
         nullable: true
       };
+      if (includeDescriptions) {
+        propertySchema.description = "Computed CASE expression";
+      }
       properties[propertyName] = propertySchema;
     } else if (projection.type === "ScalarSubquery") {
       const propertySchema = {
         type: "object",
-        description: "Subquery result",
         nullable: true
       };
+      if (includeDescriptions) {
+        propertySchema.description = "Subquery result";
+      }
       properties[propertyName] = propertySchema;
     } else if (projection.type === "CastExpression") {
       const propertySchema = {
         type: "string",
-        description: "CAST expression result",
         nullable: true
       };
+      if (includeDescriptions) {
+        propertySchema.description = "CAST expression result";
+      }
       properties[propertyName] = propertySchema;
     }
   }
@@ -7190,7 +7337,7 @@ var extractFromProjectionNodes = (table, projectionNodes, context, options) => {
     required
   };
 };
-var mapFunctionNodeToSchema = (functionName) => {
+var mapFunctionNodeToSchema = (functionName, includeDescriptions) => {
   const upperName = functionName.toUpperCase();
   switch (upperName) {
     case "COUNT":
@@ -7198,74 +7345,69 @@ var mapFunctionNodeToSchema = (functionName) => {
     case "AVG":
     case "MIN":
     case "MAX":
-      return {
+      return withOptionalDescription({
         type: "number",
-        description: `${upperName} aggregate function result`,
         nullable: false
-      };
+      }, includeDescriptions, `${upperName} aggregate function result`);
     case "GROUP_CONCAT":
     case "STRING_AGG":
     case "ARRAY_AGG":
-      return {
+      return withOptionalDescription({
         type: "string",
-        description: `${upperName} aggregate function result`,
         nullable: true
-      };
+      }, includeDescriptions, `${upperName} aggregate function result`);
     case "JSON_ARRAYAGG":
     case "JSON_OBJECTAGG":
-      return {
+      return withOptionalDescription({
         type: "object",
-        description: `${upperName} aggregate function result`,
         nullable: true
-      };
+      }, includeDescriptions, `${upperName} aggregate function result`);
     default:
-      return {
+      return withOptionalDescription({
         type: "string",
-        description: `Unknown function: ${functionName}`,
         nullable: true
-      };
+      }, includeDescriptions, `Unknown function: ${functionName}`);
   }
 };
-var mapWindowFunctionToSchema = (functionName) => {
+var mapWindowFunctionToSchema = (functionName, includeDescriptions) => {
   const upperName = functionName.toUpperCase();
   switch (upperName) {
     case "ROW_NUMBER":
     case "RANK":
     case "DENSE_RANK":
     case "NTILE":
-      return {
+      return withOptionalDescription({
         type: "integer",
-        description: `${upperName} window function result`,
         nullable: false
-      };
+      }, includeDescriptions, `${upperName} window function result`);
     case "LAG":
     case "LEAD":
     case "FIRST_VALUE":
     case "LAST_VALUE":
-      return {
+      return withOptionalDescription({
         type: "string",
-        description: `${upperName} window function result`,
         nullable: true
-      };
+      }, includeDescriptions, `${upperName} window function result`);
     default:
-      return {
+      return withOptionalDescription({
         type: "string",
-        description: `Unknown window function: ${functionName}`,
         nullable: true
-      };
+      }, includeDescriptions, `Unknown window function: ${functionName}`);
   }
 };
+var withOptionalDescription = (schema, includeDescriptions, description) => {
+  if (includeDescriptions) {
+    return { ...schema, description };
+  }
+  return schema;
+};
 var extractSelectedSchema = (table, plan, context, options) => {
   const properties = {};
   const required = [];
   plan.rootColumns.forEach((columnName) => {
     const column = table.columns[columnName];
     if (!column) return;
-    const property = mapColumnType(column);
-    if (!property.description && options.includeDescriptions && column.comment) {
-      property.description = column.comment;
-    }
-    properties[columnName] = property;
+    properties[columnName] = mapColumnType(column, options);
     if (column.notNull || column.primary) {
       required.push(columnName);
     }
@@ -7298,26 +7440,13 @@ var extractFullTableSchema = (table, context, options) => {
     return context.schemaCache.get(cacheKey);
   }
   if (context.visitedTables.has(cacheKey) && context.depth > 0) {
-    return {
-      type: "object",
-      properties: {
-        _ref: {
-          type: "string",
-          description: `Circular reference to ${table.name}`
-        }
-      },
-      required: []
-    };
+    return buildCircularReferenceSchema(table.name, "output");
   }
   context.visitedTables.add(cacheKey);
   const properties = {};
   const required = [];
   Object.entries(table.columns).forEach(([columnName, column]) => {
-    const property = mapColumnType(column);
-    if (!property.description && options.includeDescriptions && column.comment) {
-      property.description = column.comment;
-    }
-    properties[columnName] = property;
+    properties[columnName] = mapColumnType(column, options);
     if (column.notNull || column.primary) {
       required.push(columnName);
     }
@@ -7377,10 +7506,188 @@ var extractRelationSchema = (relation, relationPlan, selectedColumns, context, o
     description: targetSchema.description
   };
 };
+var buildCircularReferenceSchema = (tableName, kind) => ({
+  type: "object",
+  properties: {
+    _ref: {
+      type: "string",
+      description: `Circular ${kind} reference to ${tableName}`
+    }
+  },
+  required: []
+});
 var schemaToJson = (schema, pretty = false) => {
   return JSON.stringify(schema, null, pretty ? 2 : 0);
 };
 
+// src/openapi/query-parameters.ts
+var FILTER_PARAM_NAME = "filter";
+var buildRootTableNames = (table, from) => {
+  const names = /* @__PURE__ */ new Set([table.name]);
+  if (from?.type === "Table") {
+    names.add(from.name);
+    if (from.alias) names.add(from.alias);
+  }
+  return names;
+};
+var collectFilterColumns = (expr, table, rootTables) => {
+  const columns = /* @__PURE__ */ new Set();
+  const recordColumn = (node) => {
+    if (!rootTables.has(node.table)) return;
+    if (node.name in table.columns) {
+      columns.add(node.name);
+    }
+  };
+  const visitOrderingTerm = (term) => {
+    if (!term || typeof term !== "object") return;
+    if (isOperandNode(term)) {
+      visitOperand2(term);
+      return;
+    }
+    if ("type" in term) {
+      visitExpression2(term);
+    }
+  };
+  const visitOrderBy = (orderBy) => {
+    if (!orderBy) return;
+    orderBy.forEach((node) => visitOrderingTerm(node.term));
+  };
+  const visitOperand2 = (node) => {
+    switch (node.type) {
+      case "Column":
+        recordColumn(node);
+        return;
+      case "Function": {
+        const fn8 = node;
+        fn8.args?.forEach(visitOperand2);
+        visitOrderBy(fn8.orderBy);
+        if (fn8.separator) visitOperand2(fn8.separator);
+        return;
+      }
+      case "JsonPath": {
+        const jp = node;
+        recordColumn(jp.column);
+        return;
+      }
+      case "ScalarSubquery":
+        return;
+      case "CaseExpression": {
+        const cs = node;
+        cs.conditions.forEach((condition) => {
+          visitExpression2(condition.when);
+          visitOperand2(condition.then);
+        });
+        if (cs.else) visitOperand2(cs.else);
+        return;
+      }
+      case "Cast": {
+        const cast2 = node;
+        visitOperand2(cast2.expression);
+        return;
+      }
+      case "WindowFunction": {
+        const windowFn = node;
+        windowFn.args?.forEach(visitOperand2);
+        windowFn.partitionBy?.forEach(recordColumn);
+        visitOrderBy(windowFn.orderBy);
+        return;
+      }
+      case "ArithmeticExpression": {
+        const arith = node;
+        visitOperand2(arith.left);
+        visitOperand2(arith.right);
+        return;
+      }
+      case "BitwiseExpression": {
+        const bitwise = node;
+        visitOperand2(bitwise.left);
+        visitOperand2(bitwise.right);
+        return;
+      }
+      case "Collate": {
+        const collate2 = node;
+        visitOperand2(collate2.expression);
+        return;
+      }
+      case "AliasRef":
+      case "Literal":
+        return;
+      default:
+        return;
+    }
+  };
+  const visitExpression2 = (node) => {
+    switch (node.type) {
+      case "BinaryExpression":
+        visitOperand2(node.left);
+        visitOperand2(node.right);
+        if (node.escape) visitOperand2(node.escape);
+        return;
+      case "LogicalExpression":
+        node.operands.forEach(visitExpression2);
+        return;
+      case "NullExpression":
+        visitOperand2(node.left);
+        return;
+      case "InExpression":
+        visitOperand2(node.left);
+        if (Array.isArray(node.right)) {
+          node.right.forEach(visitOperand2);
+        }
+        return;
+      case "ExistsExpression":
+        return;
+      case "BetweenExpression":
+        visitOperand2(node.left);
+        visitOperand2(node.lower);
+        visitOperand2(node.upper);
+        return;
+      case "ArithmeticExpression":
+        visitOperand2(node.left);
+        visitOperand2(node.right);
+        return;
+      case "BitwiseExpression":
+        visitOperand2(node.left);
+        visitOperand2(node.right);
+        return;
+      default:
+        return;
+    }
+  };
+  visitExpression2(expr);
+  return columns;
+};
+var buildFilterParameters = (table, where, from, options = {}) => {
+  if (!where) return [];
+  const rootTables = buildRootTableNames(table, from);
+  const columnNames = collectFilterColumns(where, table, rootTables);
+  let schema;
+  if (columnNames.size) {
+    const properties = {};
+    for (const name of columnNames) {
+      const column = table.columns[name];
+      if (!column) continue;
+      properties[name] = mapColumnType(column, options);
+    }
+    schema = {
+      type: "object",
+      properties
+    };
+  } else {
+    schema = {
+      type: "object",
+      additionalProperties: true
+    };
+  }
+  return [{
+    name: FILTER_PARAM_NAME,
+    in: "query",
+    style: "deepObject",
+    explode: true,
+    schema
+  }];
+};
+
 // src/query-builder/select.ts
 var SelectQueryBuilder = class _SelectQueryBuilder {
   env;
@@ -8200,16 +8507,26 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     return this.context.hydration.getPlan();
   }
   /**
-   * Gets OpenAPI 3.1 JSON Schema for query result
+   * Gets OpenAPI 3.1 JSON Schemas for query output and optional input payloads
    * @param options - Schema generation options
-   * @returns OpenAPI 3.1 JSON Schema for query result
+   * @returns OpenAPI 3.1 JSON Schemas for query output and input payloads
    * @example
-   * const schema = qb.select('id', 'title', 'author').getSchema();
-   * console.log(JSON.stringify(schema, null, 2));
+   * const { output } = qb.select('id', 'title', 'author').getSchema();
+   * console.log(JSON.stringify(output, null, 2));
    */
   getSchema(options) {
     const plan = this.context.hydration.getPlan();
-    return extractSchema(this.env.table, plan, this.context.state.ast.columns, options);
+    const bundle = extractSchema(this.env.table, plan, this.context.state.ast.columns, options);
+    const parameters = buildFilterParameters(
+      this.env.table,
+      this.context.state.ast.where,
+      this.context.state.ast.from,
+      options ?? {}
+    );
+    if (parameters.length) {
+      return { ...bundle, parameters };
+    }
+    return bundle;
   }
   /**
    * Gets the Abstract Syntax Tree (AST) representation of the query
@@ -11826,6 +12143,7 @@ var UnitOfWork = class {
     const compiled = builder.compile(this.dialect);
     const results = await this.executeCompiled(compiled);
     this.applyReturningResults(tracked, results);
+    this.applyInsertId(tracked, results);
     tracked.status = "managed" /* Managed */;
     tracked.original = this.createSnapshot(tracked.table, tracked.entity);
     tracked.pk = this.getPrimaryKeyValue(tracked);
@@ -11951,6 +12269,16 @@ var UnitOfWork = class {
       tracked.entity[columnName] = row[i];
     }
   }
+  applyInsertId(tracked, results) {
+    if (this.dialect.supportsReturning()) return;
+    if (tracked.pk != null) return;
+    const pkName = findPrimaryKey(tracked.table);
+    const pkColumn = tracked.table.columns[pkName];
+    if (!pkColumn?.autoIncrement) return;
+    const insertId = results.find((result) => typeof result.insertId === "number")?.insertId;
+    if (insertId == null) return;
+    tracked.entity[pkName] = insertId;
+  }
   /**
    * Normalizes a column name by removing quotes and table prefixes.
    * @param column - The column name to normalize
@@ -13467,7 +13795,9 @@ function createMysqlExecutor(client) {
     async executeSql(sql, params) {
       const [rows] = await client.query(sql, params);
       if (!Array.isArray(rows)) {
-        return [{ columns: [], values: [] }];
+        const insertId = rows?.insertId;
+        const normalized = typeof insertId === "number" && insertId > 0 ? insertId : void 0;
+        return [{ columns: [], values: [], insertId: normalized }];
       }
       const result = rowsToQueryResult(
         rows
@@ -13766,6 +14096,7 @@ function createPooledExecutorFactory(opts) {
   bitOr,
   bitXor,
   bootstrapEntities,
+  buildFilterParameters,
   caseWhen,
   cast,
   cbrt,