@rangka/core 0.0.1

package/src/db/introspect.ts

@@ -0,0 +1,265 @@
+import type { Kysely } from 'kysely';
+import { sql } from 'kysely';
+import type {
+  ActualState,
+  ActualTable,
+  ActualColumn,
+  ActualForeignKey,
+  ActualIndex,
+  ActualCheckConstraint,
+} from './types.js';
+
+// ─── Public Entry Point ──────────────────────────────────────────────────────
+
+/**
+ * Introspects the current database schema by querying PostgreSQL system catalogs.
+ * Returns the actual state of all public tables, columns, foreign keys, indexes,
+ * and check constraints.
+ */
+export async function introspect(db: Kysely<unknown>): Promise<ActualState> {
+  const tables = await introspectTables(db);
+  return { tables };
+}
+
+// ─── Table Discovery ─────────────────────────────────────────────────────────
+
+/** Fetches all base tables in the public schema and introspects each one. */
+async function introspectTables(db: Kysely<unknown>): Promise<ActualTable[]> {
+  const { rows: tableRows } = await sql<{ table_name: string }>`
+    SELECT table_name FROM information_schema.tables
+    WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
+  `.execute(db);
+
+  const tables: ActualTable[] = [];
+
+  for (const row of tableRows) {
+    const columns = await introspectColumns(db, row.table_name);
+    const foreignKeys = await introspectForeignKeys(db, row.table_name);
+    const indexes = await introspectIndexes(db, row.table_name);
+    const checkConstraints = await introspectCheckConstraints(db, row.table_name);
+
+    tables.push({
+      name: row.table_name,
+      columns,
+      foreignKeys,
+      indexes,
+      checkConstraints,
+    });
+  }
+
+  return tables;
+}
+
+// ─── Column Introspection ────────────────────────────────────────────────────
+
+interface ColumnRow {
+  column_name: string;
+  data_type: string;
+  is_nullable: string;
+  column_default: string | null;
+  character_maximum_length: number | null;
+  numeric_precision: number | null;
+  numeric_scale: number | null;
+  udt_name: string;
+}
+
+/** Reads column metadata from information_schema for a given table. */
+async function introspectColumns(db: Kysely<unknown>, tableName: string): Promise<ActualColumn[]> {
+  const { rows: columnRows } = await sql<ColumnRow>`
+    SELECT column_name, data_type, is_nullable, column_default,
+           character_maximum_length, numeric_precision, numeric_scale, udt_name
+    FROM information_schema.columns
+    WHERE table_schema = 'public' AND table_name = ${tableName}
+    ORDER BY ordinal_position
+  `.execute(db);
+
+  return columnRows.map((row) => ({
+    name: row.column_name,
+    type: normalizeType(row),
+    nullable: row.is_nullable === 'YES',
+    defaultValue: normalizeDefault(row.column_default),
+  }));
+}
+
+// ─── Foreign Key Introspection ───────────────────────────────────────────────
+
+interface ForeignKeyRow {
+  name: string;
+  column_name: string;
+  referenced_table: string;
+  referenced_column: string;
+}
+
+/** Reads foreign key relationships for a given table. */
+async function introspectForeignKeys(
+  db: Kysely<unknown>,
+  tableName: string,
+): Promise<ActualForeignKey[]> {
+  const { rows: foreignKeyRows } = await sql<ForeignKeyRow>`
+    SELECT tc.constraint_name AS name,
+           kcu.column_name AS column_name,
+           ccu.table_name AS referenced_table,
+           ccu.column_name AS referenced_column
+    FROM information_schema.table_constraints tc
+    JOIN information_schema.key_column_usage kcu
+      ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+    JOIN information_schema.constraint_column_usage ccu
+      ON ccu.constraint_name = tc.constraint_name AND ccu.table_schema = tc.table_schema
+    WHERE tc.constraint_type = 'FOREIGN KEY'
+      AND tc.table_name = ${tableName}
+      AND tc.table_schema = 'public'
+  `.execute(db);
+
+  return foreignKeyRows.map((row) => ({
+    name: row.name,
+    column: row.column_name,
+    referencedTable: row.referenced_table,
+    referencedColumn: row.referenced_column,
+  }));
+}
+
+// ─── Index Introspection ─────────────────────────────────────────────────────
+
+interface IndexRow {
+  indexname: string;
+  indexdef: string;
+}
+
+/** Reads non-primary-key indexes for a given table from pg_indexes. */
+async function introspectIndexes(db: Kysely<unknown>, tableName: string): Promise<ActualIndex[]> {
+  const { rows: indexRows } = await sql<IndexRow>`
+    SELECT indexname, indexdef FROM pg_indexes
+    WHERE schemaname = 'public' AND tablename = ${tableName}
+  `.execute(db);
+
+  // Filter out primary key indexes (they're implicit, not user-defined)
+  return indexRows
+    .filter((row) => !row.indexname.endsWith('_pkey'))
+    .map((row) => ({
+      name: row.indexname,
+      columns: parseIndexColumns(row.indexdef),
+      unique: row.indexdef.toUpperCase().includes('UNIQUE'),
+    }));
+}
+
+// ─── Check Constraint Introspection ──────────────────────────────────────────
+
+interface CheckConstraintRow {
+  name: string;
+  expression: string;
+}
+
+/** Reads check constraints for a given table, excluding NOT NULL constraints. */
+async function introspectCheckConstraints(
+  db: Kysely<unknown>,
+  tableName: string,
+): Promise<ActualCheckConstraint[]> {
+  const { rows: constraintRows } = await sql<CheckConstraintRow>`
+    SELECT tc.constraint_name AS name,
+           cc.check_clause AS expression
+    FROM information_schema.table_constraints tc
+    JOIN information_schema.check_constraints cc
+      ON cc.constraint_name = tc.constraint_name AND cc.constraint_schema = tc.constraint_schema
+    WHERE tc.constraint_type = 'CHECK'
+      AND tc.table_name = ${tableName}
+      AND tc.table_schema = 'public'
+  `.execute(db);
+
+  // NOT NULL constraints show up as check constraints; filter them out
+  return constraintRows
+    .filter((row) => !row.name.endsWith('_not_null'))
+    .map((row) => ({
+      name: row.name,
+      column: extractColumnFromCheck(row.expression),
+      expression: row.expression,
+    }));
+}
+
+// ─── Type Normalization Helpers ──────────────────────────────────────────────
+
+/**
+ * Converts a PostgreSQL data_type (from information_schema) into a canonical
+ * uppercase SQL type string used for schema comparison.
+ */
+function normalizeType(row: ColumnRow): string {
+  const dataType = row.data_type.toLowerCase();
+
+  switch (dataType) {
+    case 'character varying':
+      return `VARCHAR(${row.character_maximum_length ?? 255})`;
+    case 'character':
+      return `CHAR(${row.character_maximum_length ?? 1})`;
+    case 'integer':
+      return 'INTEGER';
+    case 'bigint':
+      return 'BIGINT';
+    case 'smallint':
+      return 'SMALLINT';
+    case 'numeric':
+      return `DECIMAL(${row.numeric_precision ?? 18},${row.numeric_scale ?? 6})`;
+    case 'boolean':
+      return 'BOOLEAN';
+    case 'text':
+      return 'TEXT';
+    case 'date':
+      return 'DATE';
+    case 'timestamp with time zone':
+      return 'TIMESTAMPTZ';
+    case 'timestamp without time zone':
+      return 'TIMESTAMP';
+    case 'jsonb':
+      return 'JSONB';
+    case 'json':
+      return 'JSON';
+    case 'uuid':
+      return 'UUID';
+    case 'user-defined':
+      return row.udt_name.toUpperCase();
+    default:
+      return dataType.toUpperCase();
+  }
+}
+
+/**
+ * Cleans up a column_default value from information_schema:
+ * - Strips sequence references (nextval) since auto-increment is handled separately
+ * - Removes PostgreSQL type cast suffixes (e.g., 'value'::text -> 'value')
+ * - Normalizes boolean literals to uppercase
+ */
+function normalizeDefault(rawDefault: string | null): string | null {
+  if (rawDefault === null) return null;
+
+  // Auto-increment columns use nextval(); treat them as having no explicit default
+  if (rawDefault.startsWith('nextval(')) return null;
+
+  // Strip type cast suffix: 'some_value'::character varying -> 'some_value'
+  const castMatch = rawDefault.match(/^'([^']*)'::[\w\s]+$/);
+  if (castMatch) return `'${castMatch[1]}'`;
+
+  // Normalize boolean literals to uppercase for consistent comparison
+  if (rawDefault === 'true') return 'TRUE';
+  if (rawDefault === 'false') return 'FALSE';
+
+  return rawDefault;
+}
+
+// ─── Index/Constraint Parsing Helpers ────────────────────────────────────────
+
+/**
+ * Extracts column names from a CREATE INDEX definition string.
+ * Example: "CREATE INDEX idx ON tbl (col1, col2)" -> ["col1", "col2"]
+ */
+function parseIndexColumns(indexDefinition: string): string[] {
+  const match = indexDefinition.match(/\(([^)]+)\)/);
+  if (!match) return [];
+  return match[1].split(',').map((col) => col.trim().replace(/"/g, ''));
+}
+
+/**
+ * Extracts the first column name referenced in a CHECK constraint expression.
+ * Example: "(age > 0)" -> "age"
+ */
+function extractColumnFromCheck(expression: string): string {
+  const match = expression.match(/^\(?(\w+)/);
+  return match ? match[1] : '';
+}

package/src/db/model-include-resolver.ts

@@ -0,0 +1,327 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { Kysely } from 'kysely';
+import type { SchemaRegistry } from '../schema/registry.js';
+import type { ModelRelationship } from '../schema/types.js';
+import { modelToTableName } from './field-mapper.js';
+import type { AdapterRegistry } from '../plugins/adapter-registry.js';
+import type { ExternalFieldConfig } from '../external-model/types.js';
+import { mapAdapterResponse } from '../external-model/field-mapper.js';
+import { evaluateComputedFields } from '../external-model/computed-fields.js';
+
+export type IncludeSpec = string | { relation: string; nested?: IncludeSpec[] };
+
+export interface IncludeResolverOptions {
+  adapterRegistry?: AdapterRegistry;
+  externalModelFields?: Record<string, Record<string, ExternalFieldConfig>>;
+}
+
+function normalizeSpec(spec: IncludeSpec): { relation: string; nested: IncludeSpec[] } {
+  if (typeof spec === 'string') return { relation: spec, nested: [] };
+  return { relation: spec.relation, nested: spec.nested ?? [] };
+}
+
+export async function resolveModelIncludes(
+  records: Record<string, unknown>[],
+  includes: IncludeSpec[],
+  registry: SchemaRegistry,
+  db: Kysely<any>,
+  sourceModel: string,
+  options?: IncludeResolverOptions,
+): Promise<void> {
+  if (records.length === 0) return;
+
+  const relationships = registry.getRelationshipsForModel(sourceModel);
+
+  for (const spec of includes) {
+    const { relation, nested } = normalizeSpec(spec);
+    const rel = relationships.find((r) => r.field === relation);
+    if (!rel) continue;
+
+    const targetModel = registry.getModel(rel.to);
+    const isExternal = targetModel?.source != null;
+
+    if (isExternal && options?.adapterRegistry) {
+      switch (rel.type) {
+        case 'link':
+          await resolveExternalLink(
+            records,
+            rel,
+            targetModel!.source!,
+            targetModel!.qualifiedName,
+            options,
+          );
+          break;
+        case 'hasMany':
+        case 'children':
+          await resolveExternalHasMany(
+            records,
+            rel,
+            targetModel!.source!,
+            targetModel!.qualifiedName,
+            options,
+          );
+          break;
+      }
+    } else {
+      switch (rel.type) {
+        case 'link':
+          await resolveLink(records, rel, db);
+          break;
+        case 'hasMany':
+        case 'children':
+          await resolveHasMany(records, rel, db);
+          break;
+        case 'manyToMany':
+          await resolveManyToMany(records, rel, db);
+          break;
+        case 'dynamicLink':
+          await resolveDynamicLink(records, rel, db);
+          break;
+      }
+    }
+
+    if (nested.length > 0) {
+      const childRecords = records
+        .map((r) => r[rel.field])
+        .flat()
+        .filter((r): r is Record<string, unknown> => r != null && typeof r === 'object');
+
+      if (childRecords.length > 0) {
+        await resolveModelIncludes(childRecords, nested, registry, db, rel.to, options);
+      }
+    }
+  }
+}
+
+async function resolveLink(
+  records: Record<string, unknown>[],
+  rel: ModelRelationship,
+  db: Kysely<any>,
+): Promise<void> {
+  const ids = [
+    ...new Set(
+      records
+        .map((r) => r[rel.field])
+        .filter((id): id is string => id != null && typeof id === 'string'),
+    ),
+  ];
+
+  if (ids.length === 0) {
+    for (const record of records) {
+      if (record[rel.field] == null) record[rel.field] = null;
+    }
+    return;
+  }
+
+  const table = modelToTableName(rel.to);
+  const related = await db.selectFrom(table).selectAll().where('id', 'in', ids).execute();
+
+  const map = new Map<string, Record<string, unknown>>();
+  for (const row of related) {
+    map.set((row as any).id, row as Record<string, unknown>);
+  }
+
+  for (const record of records) {
+    const id = record[rel.field] as string | null;
+    record[rel.field] = id ? (map.get(id) ?? null) : null;
+  }
+}
+
+async function resolveHasMany(
+  records: Record<string, unknown>[],
+  rel: ModelRelationship,
+  db: Kysely<any>,
+): Promise<void> {
+  const parentIds = records.map((r) => r.id as string).filter(Boolean);
+  if (parentIds.length === 0) return;
+
+  const table = modelToTableName(rel.to);
+  const foreignKey = rel.foreignKey!;
+
+  const related = await db
+    .selectFrom(table)
+    .selectAll()
+    .where(foreignKey, 'in', parentIds)
+    .execute();
+
+  const grouped = new Map<string, Record<string, unknown>[]>();
+  for (const row of related as any[]) {
+    const fkValue = row[foreignKey] as string;
+    const list = grouped.get(fkValue) ?? [];
+    list.push(row);
+    grouped.set(fkValue, list);
+  }
+
+  for (const record of records) {
+    record[rel.field] = grouped.get(record.id as string) ?? [];
+  }
+}
+
+async function resolveManyToMany(
+  records: Record<string, unknown>[],
+  rel: ModelRelationship,
+  db: Kysely<any>,
+): Promise<void> {
+  const parentIds = records.map((r) => r.id as string).filter(Boolean);
+  if (parentIds.length === 0) return;
+
+  const targetTable = modelToTableName(rel.to);
+  const junctionTable = modelToTableName(rel.through!);
+
+  const sourceModelName = rel.from.split('.').pop()!;
+  const targetModelName = rel.to.split('.').pop()!;
+  const sourceFk = `${sourceModelName}_id`;
+  const targetFk = `${targetModelName}_id`;
+
+  const related = await db
+    .selectFrom(targetTable)
+    .selectAll(targetTable)
+    .select(`${junctionTable}.${sourceFk} as _source_fk`)
+    .innerJoin(junctionTable, `${junctionTable}.${targetFk}`, `${targetTable}.id`)
+    .where(`${junctionTable}.${sourceFk}`, 'in', parentIds)
+    .execute();
+
+  const grouped = new Map<string, Record<string, unknown>[]>();
+  for (const row of related as any[]) {
+    const fkValue = row._source_fk as string;
+    const clean = { ...row };
+    delete clean._source_fk;
+    const list = grouped.get(fkValue) ?? [];
+    list.push(clean);
+    grouped.set(fkValue, list);
+  }
+
+  for (const record of records) {
+    record[rel.field] = grouped.get(record.id as string) ?? [];
+  }
+}
+
+async function resolveDynamicLink(
+  records: Record<string, unknown>[],
+  rel: ModelRelationship,
+  db: Kysely<any>,
+): Promise<void> {
+  const modelField = rel.modelField!;
+
+  const groups = new Map<string, { records: Record<string, unknown>[]; ids: string[] }>();
+  for (const record of records) {
+    const targetModel = record[modelField] as string | null;
+    const id = record[rel.field] as string | null;
+    if (!targetModel || !id) {
+      record[rel.field] = null;
+      continue;
+    }
+    const group = groups.get(targetModel) ?? { records: [], ids: [] };
+    group.records.push(record);
+    group.ids.push(id);
+    groups.set(targetModel, group);
+  }
+
+  for (const [targetModel, group] of groups) {
+    const table = modelToTableName(targetModel);
+    const uniqueIds = [...new Set(group.ids)];
+
+    const related = await db.selectFrom(table).selectAll().where('id', 'in', uniqueIds).execute();
+
+    const map = new Map<string, Record<string, unknown>>();
+    for (const row of related as any[]) {
+      map.set(row.id, row);
+    }
+
+    for (const record of group.records) {
+      const id = record[rel.field] as string;
+      record[rel.field] = map.get(id) ?? null;
+    }
+  }
+}
+
+async function resolveExternalLink(
+  records: Record<string, unknown>[],
+  rel: ModelRelationship,
+  adapterSource: string,
+  qualifiedName: string,
+  options: IncludeResolverOptions,
+): Promise<void> {
+  const ids = [
+    ...new Set(
+      records
+        .map((r) => r[rel.field])
+        .filter((id): id is string => id != null && typeof id === 'string'),
+    ),
+  ];
+
+  if (ids.length === 0) {
+    for (const record of records) {
+      if (record[rel.field] == null) record[rel.field] = null;
+    }
+    return;
+  }
+
+  const adapter = options.adapterRegistry!.get(adapterSource);
+  const fields = options.externalModelFields?.[qualifiedName] ?? {};
+
+  let related: Record<string, unknown>[];
+  if (adapter.batchGet) {
+    related = await adapter.batchGet(qualifiedName, ids);
+  } else {
+    const results = await Promise.all(ids.map((id) => adapter.get(qualifiedName, id)));
+    related = results.filter((r): r is Record<string, unknown> => r != null);
+  }
+
+  const mapped = related.map((raw) => {
+    const m = mapAdapterResponse(raw, fields);
+    return evaluateComputedFields(m, fields);
+  });
+
+  const map = new Map<string, Record<string, unknown>>();
+  for (const row of mapped) {
+    if (row.id != null) map.set(row.id as string, row);
+  }
+
+  for (const record of records) {
+    const id = record[rel.field] as string | null;
+    record[rel.field] = id ? (map.get(id) ?? null) : null;
+  }
+}
+
+async function resolveExternalHasMany(
+  records: Record<string, unknown>[],
+  rel: ModelRelationship,
+  adapterSource: string,
+  qualifiedName: string,
+  options: IncludeResolverOptions,
+): Promise<void> {
+  const parentIds = records.map((r) => r.id as string).filter(Boolean);
+  if (parentIds.length === 0) return;
+
+  const adapter = options.adapterRegistry!.get(adapterSource);
+  const fields = options.externalModelFields?.[qualifiedName] ?? {};
+  const foreignKey = rel.foreignKey!;
+
+  let allRelated: Record<string, unknown>[] = [];
+
+  if (adapter.list) {
+    const result = await adapter.list(qualifiedName, {
+      filters: [{ field: foreignKey, operator: 'in', value: parentIds }],
+    });
+    allRelated = result.data;
+  }
+
+  const mapped = allRelated.map((raw) => {
+    const m = mapAdapterResponse(raw, fields);
+    return evaluateComputedFields(m, fields);
+  });
+
+  const grouped = new Map<string, Record<string, unknown>[]>();
+  for (const row of mapped) {
+    const fkValue = row[foreignKey] as string;
+    if (!fkValue) continue;
+    const list = grouped.get(fkValue) ?? [];
+    list.push(row);
+    grouped.set(fkValue, list);
+  }
+
+  for (const record of records) {
+    record[rel.field] = grouped.get(record.id as string) ?? [];
+  }
+}