metal-orm 1.0.79 → 1.0.80

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.79",
+  "version": "1.0.80",
   "type": "module",
   "types": "./dist/index.d.ts",
   "engines": {
@@ -29,6 +29,10 @@
     "gen:entities": "node scripts/generate-entities.mjs",
     "test": "vitest",
     "test:ui": "vitest --ui",
+    "test:mysql": "vitest --run tests/e2e/mysql-memory.test.ts tests/e2e/decorators-mysql-memory.test.ts tests/e2e/save-graph-mysql-memory.test.ts",
+    "test:sqlite": "vitest --run tests/e2e/sqlite-memory.test.ts tests/e2e/decorators-sqlite-memory.test.ts tests/e2e/save-graph-sqlite-memory.test.ts",
+    "test:pglite": "vitest --run tests/e2e/pglite-memory.test.ts",
+    "test:e2e": "vitest tests/e2e",
     "show-sql": "node scripts/show-sql.mjs",
     "lint": "node scripts/run-eslint.mjs",
     "lint:fix": "node scripts/run-eslint.mjs --fix"
@@ -54,11 +58,13 @@
     }
   },
   "devDependencies": {
-    "@vitest/ui": "^4.0.14",
+    "@electric-sql/pglite": "^0.3.14",
     "@typescript-eslint/eslint-plugin": "^8.20.0",
     "@typescript-eslint/parser": "^8.20.0",
+    "@vitest/ui": "^4.0.14",
     "eslint": "^8.57.0",
     "eslint-plugin-deprecation": "^3.0.0",
+    "mysql-memory-server": "^1.13.0",
     "mysql2": "^3.15.3",
     "pg": "^8.16.3",
     "sqlite3": "^5.1.7",

package/src/core/dialect/postgres/index.ts

@@ -33,11 +33,15 @@ export class PostgresDialect extends SqlDialectBase {
    * @param id - Identifier to quote
    * @returns Quoted identifier
    */
-  quoteIdentifier(id: string): string {
-    return `"${id}"`;
-  }
-
-  /**
+  quoteIdentifier(id: string): string {
+    return `"${id}"`;
+  }
+
+  protected formatPlaceholder(index: number): string {
+    return `$${index}`;
+  }
+
+  /**
    * Compiles JSON path expression using PostgreSQL syntax
    * @param node - JSON path node
    * @returns PostgreSQL JSON path expression

package/src/index.ts

@@ -41,16 +41,18 @@ export * from './orm/relations/has-many.js';
 export * from './orm/relations/belongs-to.js';
 export * from './orm/relations/many-to-many.js';
 export * from './orm/execute.js';
-export type { EntityContext } from './orm/entity-context.js';
-export type { PrimaryKey as EntityPrimaryKey } from './orm/entity-context.js';
+export type { EntityContext } from './orm/entity-context.js';
+export type { PrimaryKey as EntityPrimaryKey } from './orm/entity-context.js';
 export * from './orm/execution-context.js';
 export * from './orm/hydration-context.js';
 export * from './orm/domain-event-bus.js';
 export * from './orm/runtime-types.js';
 export * from './orm/query-logger.js';
+export * from './orm/interceptor-pipeline.js';
 export * from './orm/jsonify.js';
-export * from './orm/save-graph-types.js';
-export * from './decorators/index.js';
+export * from './orm/save-graph-types.js';
+export * from './decorators/index.js';
+export * from './openapi/index.js';
 
 // NEW: execution abstraction + helpers
 export * from './core/execution/db-executor.js';

package/src/openapi/index.ts

@@ -0,0 +1,3 @@
+export * from './schema-types.js';
+export * from './type-mappers.js';
+export * from './schema-extractor.js';

package/src/openapi/schema-extractor.ts

@@ -0,0 +1,418 @@
+import type { TableDef } from '../schema/table.js';
+import type { RelationDef } from '../schema/relation.js';
+import type { HydrationPlan, HydrationRelationPlan } from '../core/hydration/types.js';
+import type { ProjectionNode } from '../query-builder/select-query-state.js';
+
+import type { OpenApiSchema, SchemaExtractionContext, SchemaOptions, JsonSchemaProperty, JsonSchemaType } from './schema-types.js';
+import { mapColumnType, mapRelationType } from './type-mappers.js';
+
+/**
+ * Extracts OpenAPI 3.1 schema from a query builder's hydration plan
+ * @param table - Table definition
+ * @param plan - Hydration plan from query builder
+ * @param projectionNodes - Projection AST nodes (for computed fields)
+ * @param options - Schema generation options
+ * @returns OpenAPI 3.1 JSON Schema
+ */
+export const extractSchema = (
+  table: TableDef,
+  plan: HydrationPlan | undefined,
+  projectionNodes: ProjectionNode[] | undefined,
+  options: SchemaOptions = {}
+): OpenApiSchema => {
+  const mode = options.mode ?? 'full';
+
+  const context: SchemaExtractionContext = {
+    visitedTables: new Set(),
+    schemaCache: new Map(),
+    depth: 0,
+    maxDepth: options.maxDepth ?? 5,
+  };
+
+  // Detect if query contains computed fields (non-Column nodes)
+  const hasComputedFields = projectionNodes && projectionNodes.some(
+    node => node.type !== 'Column'
+  );
+
+  if (hasComputedFields) {
+    // Use projection-based extraction for computed fields + relations
+    return extractFromProjectionNodes(table, projectionNodes!, context, options);
+  }
+
+  if (mode === 'selected' && plan) {
+    return extractSelectedSchema(table, plan, context, options);
+  }
+
+  return extractFullTableSchema(table, context, options);
+};
+
+/**
+ * Extracts schema from projection nodes (handles computed fields)
+ * @param table - Table definition
+ * @param projectionNodes - Projection AST nodes
+ * @param context - Schema extraction context
+ * @param options - Schema generation options
+ * @returns OpenAPI 3.1 JSON Schema
+ */
+const extractFromProjectionNodes = (
+  table: TableDef,
+  projectionNodes: ProjectionNode[],
+  context: SchemaExtractionContext,
+  options: SchemaOptions
+): OpenApiSchema => {
+  const properties: Record<string, JsonSchemaProperty> = {};
+  const required: string[] = [];
+
+  for (const node of projectionNodes) {
+    if (!node || typeof node !== 'object') continue;
+
+    const projection = node as { type: string; alias?: string; fn?: string; value?: unknown };
+    const propertyName = projection.alias ?? '';
+
+    if (!propertyName) continue;
+
+    if (projection.type === 'Column') {
+      const columnNode = node as { table: string; name: string };
+      const column = table.columns[columnNode.name];
+      if (!column) continue;
+
+      const property = mapColumnType(column);
+      if (!property.description && options.includeDescriptions && column.comment) {
+        property.description = column.comment;
+      }
+
+      properties[propertyName] = property;
+
+      if (column.notNull || column.primary) {
+        required.push(propertyName);
+      }
+    } else if (projection.type === 'Function' || projection.type === 'WindowFunction') {
+      const fnNode = node as { fn?: string; name?: string };
+      const functionName = fnNode.fn?.toUpperCase() ?? fnNode.name?.toUpperCase() ?? '';
+      const propertySchema = projection.type === 'Function' 
+        ? mapFunctionNodeToSchema(functionName)
+        : mapWindowFunctionToSchema(functionName);
+      
+      properties[propertyName] = propertySchema;
+
+      const isCountFunction = functionName === 'COUNT';
+      const isWindowRankFunction = functionName === 'ROW_NUMBER' || functionName === 'RANK';
+      
+      if (isCountFunction || isWindowRankFunction) {
+        required.push(propertyName);
+      }
+    } else if (projection.type === 'CaseExpression') {
+      const propertySchema: JsonSchemaProperty = {
+        type: 'string' as JsonSchemaType,
+        description: 'Computed CASE expression',
+        nullable: true,
+      };
+      properties[propertyName] = propertySchema;
+    } else if (projection.type === 'ScalarSubquery') {
+      const propertySchema: JsonSchemaProperty = {
+        type: 'object' as JsonSchemaType,
+        description: 'Subquery result',
+        nullable: true,
+      };
+      properties[propertyName] = propertySchema;
+    } else if (projection.type === 'CastExpression') {
+      const propertySchema: JsonSchemaProperty = {
+        type: 'string' as JsonSchemaType,
+        description: 'CAST expression result',
+        nullable: true,
+      };
+      properties[propertyName] = propertySchema;
+    }
+  }
+
+  return {
+    type: 'object',
+    properties,
+    required,
+  };
+};
+
+/**
+ * Maps SQL aggregate functions to OpenAPI types
+ * @param functionName - SQL function name
+ * @returns OpenAPI JSON Schema property
+ */
+const mapFunctionNodeToSchema = (functionName: string): JsonSchemaProperty => {
+  const upperName = functionName.toUpperCase();
+
+  switch (upperName) {
+    case 'COUNT':
+    case 'SUM':
+    case 'AVG':
+    case 'MIN':
+    case 'MAX':
+      return {
+        type: 'number' as JsonSchemaType,
+        description: `${upperName} aggregate function result`,
+        nullable: false,
+      };
+
+    case 'GROUP_CONCAT':
+    case 'STRING_AGG':
+    case 'ARRAY_AGG':
+      return {
+        type: 'string' as JsonSchemaType,
+        description: `${upperName} aggregate function result`,
+        nullable: true,
+      };
+
+    case 'JSON_ARRAYAGG':
+    case 'JSON_OBJECTAGG':
+      return {
+        type: 'object' as JsonSchemaType,
+        description: `${upperName} aggregate function result`,
+        nullable: true,
+      };
+
+    default:
+      return {
+        type: 'string' as JsonSchemaType,
+        description: `Unknown function: ${functionName}`,
+        nullable: true,
+      };
+  }
+};
+
+/**
+ * Maps SQL window functions to OpenAPI types
+ * @param functionName - SQL function name
+ * @returns OpenAPI JSON Schema property
+ */
+const mapWindowFunctionToSchema = (functionName: string): JsonSchemaProperty => {
+  const upperName = functionName.toUpperCase();
+
+  switch (upperName) {
+    case 'ROW_NUMBER':
+    case 'RANK':
+    case 'DENSE_RANK':
+    case 'NTILE':
+      return {
+        type: 'integer' as JsonSchemaType,
+        description: `${upperName} window function result`,
+        nullable: false,
+      };
+
+    case 'LAG':
+    case 'LEAD':
+    case 'FIRST_VALUE':
+    case 'LAST_VALUE':
+      return {
+        type: 'string' as JsonSchemaType,
+        description: `${upperName} window function result`,
+        nullable: true,
+      };
+
+    default:
+      return {
+        type: 'string' as JsonSchemaType,
+        description: `Unknown window function: ${functionName}`,
+        nullable: true,
+      };
+  }
+};
+
+/**
+ * Extracts schema with only selected columns and relations
+ * @param table - Table definition
+ * @param plan - Hydration plan
+ * @param context - Schema extraction context
+ * @param options - Schema generation options
+ * @returns OpenAPI 3.1 JSON Schema
+ */
+const extractSelectedSchema = (
+  table: TableDef,
+  plan: HydrationPlan,
+  context: SchemaExtractionContext,
+  options: SchemaOptions
+): OpenApiSchema => {
+  const properties: Record<string, JsonSchemaProperty> = {};
+  const required: string[] = [];
+
+  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;
+
+    if (column.notNull || column.primary) {
+      required.push(columnName);
+    }
+  });
+
+  plan.relations.forEach(relationPlan => {
+    const relation = table.relations[relationPlan.name];
+    if (!relation) return;
+
+    const relationSchema = extractRelationSchema(
+      relation,
+      relationPlan,
+      relationPlan.columns,
+      context,
+      options
+    );
+
+    properties[relationPlan.name] = relationSchema;
+
+    const { isNullable } = mapRelationType(relation.type);
+    if (!isNullable && relationPlan.name) {
+      required.push(relationPlan.name);
+    }
+  });
+
+  return {
+    type: 'object',
+    properties,
+    required,
+  };
+};
+
+/**
+ * Extracts full table schema (all columns, all relations)
+ * @param table - Table definition
+ * @param context - Schema extraction context
+ * @param options - Schema generation options
+ * @returns OpenAPI 3.1 JSON Schema
+ */
+const extractFullTableSchema = (
+  table: TableDef,
+  context: SchemaExtractionContext,
+  options: SchemaOptions
+): OpenApiSchema => {
+  const cacheKey = table.name;
+
+  if (context.schemaCache.has(cacheKey)) {
+    return context.schemaCache.get(cacheKey)!;
+  }
+
+  if (context.visitedTables.has(cacheKey) && context.depth > 0) {
+    return {
+      type: 'object',
+      properties: {
+        _ref: {
+          type: 'string' as JsonSchemaType,
+          description: `Circular reference to ${table.name}`,
+        },
+      },
+      required: [],
+    };
+  }
+
+  context.visitedTables.add(cacheKey);
+
+  const properties: Record<string, JsonSchemaProperty> = {};
+  const required: string[] = [];
+
+  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;
+
+    if (column.notNull || column.primary) {
+      required.push(columnName);
+    }
+  });
+
+  Object.entries(table.relations).forEach(([relationName, relation]) => {
+    if (context.depth >= context.maxDepth) {
+      return;
+    }
+
+    const relationSchema = extractRelationSchema(
+      relation,
+      undefined,
+      [],
+      { ...context, depth: context.depth + 1 },
+      options
+    );
+
+    properties[relationName] = relationSchema;
+
+    const { isNullable } = mapRelationType(relation.type);
+    if (!isNullable) {
+      required.push(relationName);
+    }
+  });
+
+  const schema: OpenApiSchema = {
+    type: 'object',
+    properties,
+    required,
+  };
+
+  context.schemaCache.set(cacheKey, schema);
+  return schema;
+};
+
+/**
+ * Extracts schema for a single relation
+ * @param relation - Relation definition
+ * @param relationPlan - Hydration plan for relation
+ * @param selectedColumns - Selected columns from relation
+ * @param context - Schema extraction context
+ * @param options - Schema generation options
+ * @returns OpenAPI JSON Schema property for relation
+ */
+const extractRelationSchema = (
+  relation: RelationDef,
+  relationPlan: HydrationRelationPlan | undefined,
+  selectedColumns: string[],
+  context: SchemaExtractionContext,
+  options: SchemaOptions
+): JsonSchemaProperty => {
+  const targetTable = relation.target;
+  const { type: relationType, isNullable } = mapRelationType(relation.type);
+
+  let targetSchema: OpenApiSchema;
+
+  if (relationPlan && selectedColumns.length > 0) {
+    const plan: HydrationPlan = {
+      rootTable: targetTable.name,
+      rootPrimaryKey: relationPlan.targetPrimaryKey,
+      rootColumns: selectedColumns,
+      relations: [],
+    };
+
+    targetSchema = extractSelectedSchema(targetTable, plan, context, options);
+  } else {
+    targetSchema = extractFullTableSchema(targetTable, context, options);
+  }
+
+  if (relationType === 'array') {
+    return {
+      type: 'array',
+      items: targetSchema as JsonSchemaProperty,
+      nullable: isNullable,
+    };
+  }
+
+  return {
+    type: 'object' as JsonSchemaType,
+    properties: targetSchema.properties,
+    required: targetSchema.required,
+    nullable: isNullable,
+    description: targetSchema.description,
+  };
+};
+
+/**
+ * Converts a schema to a JSON string with optional pretty printing
+ * @param schema - OpenAPI schema
+ * @param pretty - Whether to pretty print
+ * @returns JSON string
+ */
+export const schemaToJson = (schema: OpenApiSchema, pretty = false): string => {
+  return JSON.stringify(schema, null, pretty ? 2 : 0);
+};

package/src/openapi/schema-types.ts

@@ -0,0 +1,92 @@
+/**
+ * OpenAPI 3.1 JSON Schema type representation
+ */
+export type JsonSchemaType = 
+  | 'string' 
+  | 'number' 
+  | 'integer' 
+  | 'boolean' 
+  | 'object' 
+  | 'array' 
+  | 'null';
+
+/**
+ * Common OpenAPI 3.1 JSON Schema formats
+ */
+export type JsonSchemaFormat = 
+  | 'date-time' 
+  | 'date' 
+  | 'time' 
+  | 'email' 
+  | 'uuid' 
+  | 'uri' 
+  | 'binary' 
+  | 'base64';
+
+/**
+ * OpenAPI 3.1 JSON Schema property definition
+ */
+export interface JsonSchemaProperty {
+  type?: JsonSchemaType | JsonSchemaType[];
+  format?: JsonSchemaFormat;
+  description?: string;
+  nullable?: boolean;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  enum?: (string | number | boolean)[];
+  default?: unknown;
+  example?: unknown;
+  properties?: Record<string, JsonSchemaProperty>;
+  required?: string[];
+  items?: JsonSchemaProperty;
+  $ref?: string;
+  anyOf?: JsonSchemaProperty[];
+  allOf?: JsonSchemaProperty[];
+  oneOf?: JsonSchemaProperty[];
+  [key: string]: unknown;
+}
+
+/**
+ * Complete OpenAPI 3.1 Schema for an entity or query result
+ */
+export interface OpenApiSchema {
+  type: 'object';
+  properties: Record<string, JsonSchemaProperty>;
+  required: string[];
+  description?: string;
+}
+
+/**
+ * Schema generation options
+ */
+export interface SchemaOptions {
+  /** Use selected columns only (from select/include) vs full entity */
+  mode?: 'selected' | 'full';
+  /** Include description from column comments */
+  includeDescriptions?: boolean;
+  /** Include enum values for enum columns */
+  includeEnums?: boolean;
+  /** Include column examples if available */
+  includeExamples?: boolean;
+  /** Format output for pretty printing (debugging) */
+  pretty?: boolean;
+  /** Maximum depth for relation recursion */
+  maxDepth?: number;
+}
+
+/**
+ * Schema extraction context for handling circular references
+ */
+export interface SchemaExtractionContext {
+  /** Set of already visited tables to detect cycles */
+  visitedTables: Set<string>;
+  /** Map of table names to their generated schemas */
+  schemaCache: Map<string, OpenApiSchema>;
+  /** Current extraction depth */
+  depth: number;
+  /** Maximum depth to recurse */
+  maxDepth: number;
+}