@aruvili/api 0.1.0

package/src/routes/meta.ts

@@ -0,0 +1,448 @@
+import { Hono } from 'hono';
+import { validateDocType, generateCreateTableDDL, generateAlterTableDDL, getTableName, DocTypeDefinition } from '@aruvili/core';
+import { query, withTransaction } from '../db.js';
+import { registry } from '../registry.js';
+
+export const metaRouter = new Hono();
+
+/**
+ * Helper to fetch existing columns in target table from postgres database catalog.
+ */
+async function getExistingColumns(client: any, tableName: string, schema: string) {
+  const sql = `
+    SELECT 
+      column_name AS "columnName", 
+      data_type AS "dataType", 
+      is_nullable = 'YES' AS "isNullable", 
+      character_maximum_length AS "characterMaximumLength"
+    FROM information_schema.columns
+    WHERE table_name = $1 AND table_schema = $2
+  `;
+  const res = await client.query(sql, [tableName, schema]);
+  return res.rows;
+}
+
+/**
+ * Helper to execute schema synchronization across all registered tenant schemas.
+ */
+async function syncDatabaseSchema(client: any, definition: DocTypeDefinition) {
+  const tableName = getTableName(definition.name);
+
+  // Fetch all active tenants
+  const tenantsRes = await client.query('SELECT id FROM _tenants');
+  const tenantIds = tenantsRes.rows.map((r: any) => r.id);
+
+  // Sync both public schema and all tenant schemas
+  const schemas = Array.from(new Set(['public', ...tenantIds]));
+  let totalDdlExecuted: string[] = [];
+
+  for (const schema of schemas) {
+    // 1. Temporarily swap search path to target schema
+    await client.query(`SET search_path TO ${schema}, public`);
+
+    // 2. Check if table exists in the target schema
+    const checkTableRes = await client.query(
+      `SELECT EXISTS (
+        SELECT FROM information_schema.tables 
+        WHERE table_name = $1 AND table_schema = $2
+      )`,
+      [tableName, schema]
+    );
+    const tableExists = checkTableRes.rows[0].exists;
+
+    let ddl: string[] = [];
+    if (!tableExists) {
+      ddl = generateCreateTableDDL(definition);
+    } else {
+      const cols = await getExistingColumns(client, tableName, schema);
+      ddl = generateAlterTableDDL(definition, cols);
+    }
+
+    // 3. Run migration DDL
+    for (const sql of ddl) {
+      await client.query(sql);
+      totalDdlExecuted.push(`[${schema}] ${sql}`);
+    }
+  }
+
+  return totalDdlExecuted;
+}
+
+/**
+ * POST /api/meta/doctypes
+ * Create a new DocType. Fails with 409 Conflict if duplicate.
+ */
+metaRouter.post('/doctypes', async (c) => {
+  const definition = await c.req.json() as DocTypeDefinition;
+
+  // 1. Perform structural integrity checks on the submitted definition
+  const valResult = validateDocType(definition);
+  if (!valResult.valid) {
+    return c.json({ error: 'Schema validation failed', details: valResult.errors }, 400);
+  }
+
+  try {
+    const output = await withTransaction(async (client) => {
+      // 2. Check if DocType already exists to satisfy Task 2.1
+      const checkExists = await client.query('SELECT 1 FROM _doctype_meta WHERE name = $1', [definition.name]);
+      if (checkExists.rows.length > 0) {
+        throw new Error(`Conflict: DocType '${definition.name}' already exists.`);
+      }
+
+      // 3. Insert active metadata registry record
+      await client.query(
+        `INSERT INTO _doctype_meta (name, definition, updated_at)
+         VALUES ($1, $2, NOW())`,
+        [definition.name, JSON.stringify(definition)]
+      );
+
+      // 4. Perform dynamic schema synchronization across all tenant databases
+      const ddlExecuted = await syncDatabaseSchema(client, definition);
+
+      // 5. Log migration history
+      if (ddlExecuted.length > 0) {
+        await client.query(
+          `INSERT INTO _doctype_migration_history (doctype_name, version, ddl_executed, executed_by)
+           VALUES ($1, 1, $2, $3)`,
+          [definition.name, ddlExecuted.join('\n'), 'System Admin']
+        );
+      }
+
+      // 6. Log version history tracking (Task 2.3)
+      await client.query(
+        `INSERT INTO _doctype_definition_history (doctype_name, version, definition, changed_by, ddl_applied, notes)
+         VALUES ($1, 1, $2, $3, $4, $5)`,
+        [
+          definition.name,
+          JSON.stringify(definition),
+          'System Admin',
+          ddlExecuted.join('\n'),
+          'Initial definition creation'
+        ]
+      );
+
+      // Invalidate cache immediately
+      registry.invalidate(definition.name);
+
+      return {
+        doctype: definition.name,
+        table: getTableName(definition.name),
+        action: 'CREATED',
+        version: 1,
+        changes_applied: ddlExecuted
+      };
+    });
+
+    return c.json(output);
+  } catch (err: any) {
+    if (err.message.includes('Conflict:')) {
+      return c.json({ error: err.message }, 409);
+    }
+    console.error('Doctype creation failed:', err);
+    return c.json({ error: 'Failed to create database metadata', details: err.message }, 500);
+  }
+});
+
+/**
+ * PUT /api/meta/doctypes/:name
+ * Update an existing DocType definition.
+ */
+metaRouter.put('/doctypes/:name', async (c) => {
+  const name = c.req.param('name');
+  const definition = await c.req.json() as DocTypeDefinition;
+
+  if (definition.name !== name) {
+    return c.json({ error: 'Doctype name mismatch between URL and payload' }, 400);
+  }
+
+  // 1. Perform structural integrity checks on the submitted definition
+  const valResult = validateDocType(definition);
+  if (!valResult.valid) {
+    return c.json({ error: 'Schema validation failed', details: valResult.errors }, 400);
+  }
+
+  try {
+    const output = await withTransaction(async (client) => {
+      // 2. Verify existence
+      const checkExists = await client.query('SELECT 1 FROM _doctype_meta WHERE name = $1', [name]);
+      if (checkExists.rows.length === 0) {
+        throw new Error(`NotFound: DocType '${name}' does not exist.`);
+      }
+
+      // 3. Compute next version number
+      const versionRes = await client.query(
+        'SELECT COALESCE(MAX(version), 0) + 1 AS next FROM _doctype_definition_history WHERE doctype_name = $1',
+        [name]
+      );
+      const nextVersion = versionRes.rows[0].next;
+
+      // 4. Perform dynamic schema synchronization across all tenant databases
+      const ddlExecuted = await syncDatabaseSchema(client, definition);
+
+      // 5. Update active registry
+      await client.query(
+        `UPDATE _doctype_meta SET definition = $2, updated_at = NOW() WHERE name = $1`,
+        [name, JSON.stringify(definition)]
+      );
+
+      // 6. Log migration history
+      if (ddlExecuted.length > 0) {
+        await client.query(
+          `INSERT INTO _doctype_migration_history (doctype_name, version, ddl_executed, executed_by)
+           VALUES ($1, $2, $3, $4)`,
+          [name, nextVersion, ddlExecuted.join('\n'), 'System Admin']
+        );
+      }
+
+      // 7. Log version history tracking (Task 2.3)
+      await client.query(
+        `INSERT INTO _doctype_definition_history (doctype_name, version, definition, changed_by, ddl_applied, notes)
+         VALUES ($1, $2, $3, $4, $5, $6)`,
+        [
+          name,
+          nextVersion,
+          JSON.stringify(definition),
+          'System Admin',
+          ddlExecuted.join('\n'),
+          'Updated definition schema'
+        ]
+      );
+
+      // Invalidate cache
+      registry.invalidate(name);
+
+      return {
+        doctype: name,
+        table: getTableName(name),
+        action: 'MIGRATED',
+        version: nextVersion,
+        changes_applied: ddlExecuted
+      };
+    });
+
+    return c.json(output);
+  } catch (err: any) {
+    if (err.message.includes('NotFound:')) {
+      return c.json({ error: err.message }, 404);
+    }
+    console.error('Doctype update failed:', err);
+    return c.json({ error: 'Failed to update database metadata', details: err.message }, 500);
+  }
+});
+
+/**
+ * GET /api/meta/doctypes/:name/history
+ * Retrieve historical configuration log.
+ */
+metaRouter.get('/doctypes/:name/history', async (c) => {
+  const name = c.req.param('name');
+  try {
+    const res = await query(
+      `SELECT version, changed_by, changed_at, notes, ddl_applied, definition
+       FROM _doctype_definition_history
+       WHERE doctype_name = $1
+       ORDER BY version DESC`,
+      [name]
+    );
+    return c.json(res.rows);
+  } catch (err: any) {
+    return c.json({ error: 'Failed to fetch metadata history', details: err.message }, 500);
+  }
+});
+
+/**
+ * POST /api/meta/doctypes/:name/revert
+ * Revert doctype metadata schema and trigger safe migrations to target version.
+ */
+metaRouter.post('/doctypes/:name/revert', async (c) => {
+  const name = c.req.param('name');
+  const body = await c.req.json();
+  const targetVersion = body.version;
+
+  if (typeof targetVersion !== 'number') {
+    return c.json({ error: 'Missing or invalid version number in body' }, 400);
+  }
+
+  try {
+    const output = await withTransaction(async (client) => {
+      // 1. Retrieve definition from history
+      const historyRes = await client.query(
+        `SELECT definition FROM _doctype_definition_history 
+         WHERE doctype_name = $1 AND version = $2`,
+        [name, targetVersion]
+      );
+      if (historyRes.rows.length === 0) {
+        throw new Error(`NotFound: Version ${targetVersion} for DocType '${name}' was not found.`);
+      }
+      const targetDefinition = historyRes.rows[0].definition as DocTypeDefinition;
+
+      // 2. Compute next version number
+      const versionRes = await client.query(
+        'SELECT COALESCE(MAX(version), 0) + 1 AS next FROM _doctype_definition_history WHERE doctype_name = $1',
+        [name]
+      );
+      const nextVersion = versionRes.rows[0].next;
+
+      // 3. Perform dynamic schema synchronization across all tenant databases
+      const ddlExecuted = await syncDatabaseSchema(client, targetDefinition);
+
+      // 4. Update active registry
+      await client.query(
+        `UPDATE _doctype_meta SET definition = $2, updated_at = NOW() WHERE name = $1`,
+        [name, JSON.stringify(targetDefinition)]
+      );
+
+      // 5. Log migration history
+      if (ddlExecuted.length > 0) {
+        await client.query(
+          `INSERT INTO _doctype_migration_history (doctype_name, version, ddl_executed, executed_by)
+           VALUES ($1, $2, $3, $4)`,
+          [name, nextVersion, ddlExecuted.join('\n'), 'System Admin']
+        );
+      }
+
+      // 6. Log version history tracking
+      await client.query(
+        `INSERT INTO _doctype_definition_history (doctype_name, version, definition, changed_by, ddl_applied, notes)
+         VALUES ($1, $2, $3, $4, $5, $6)`,
+        [
+          name,
+          nextVersion,
+          JSON.stringify(targetDefinition),
+          'System Admin',
+          ddlExecuted.join('\n'),
+          `Reverted active schema to version ${targetVersion}`
+        ]
+      );
+
+      // Invalidate cache
+      registry.invalidate(name);
+
+      return {
+        doctype: name,
+        table: getTableName(name),
+        action: 'REVERTED',
+        version: nextVersion,
+        changes_applied: ddlExecuted
+      };
+    });
+
+    return c.json(output);
+  } catch (err: any) {
+    if (err.message.includes('NotFound:')) {
+      return c.json({ error: err.message }, 404);
+    }
+    console.error('Revert failed:', err);
+    return c.json({ error: 'Failed to revert metadata schema', details: err.message }, 500);
+  }
+});
+
+/**
+ * POST /api/meta/tenants
+ * Register a new tenant, create its Postgres schema, and migrate all existing definitions.
+ */
+metaRouter.post('/tenants', async (c) => {
+  const body = await c.req.json();
+  const { id, name, domain } = body;
+
+  if (!id || !name) {
+    return c.json({ error: 'Tenant id and name are required' }, 400);
+  }
+
+  const TENANT_REGEX = /^[a-zA-Z0-9_]{1,63}$/;
+  if (!TENANT_REGEX.test(id)) {
+    return c.json({ error: 'Invalid Tenant ID format' }, 400);
+  }
+
+  const tenantId = id.toLowerCase().trim();
+
+  try {
+    const output = await withTransaction(async (client) => {
+      // 1. Check if tenant already exists
+      const checkRes = await client.query('SELECT 1 FROM _tenants WHERE id = $1', [tenantId]);
+      if (checkRes.rows.length > 0) {
+        throw new Error(`Conflict: Tenant '${tenantId}' already exists.`);
+      }
+
+      // 2. Insert tenant record into central _tenants table
+      await client.query(
+        `INSERT INTO _tenants (id, name, domain) VALUES ($1, $2, $3)`,
+        [tenantId, name, domain || null]
+      );
+
+      // 3. Create the schema for the tenant
+      await client.query(`CREATE SCHEMA IF NOT EXISTS ${tenantId}`);
+
+      // 4. Retrieve all current doctypes to copy schemas to the new tenant schema
+      const doctypesRes = await client.query('SELECT definition FROM _doctype_meta');
+      const doctypes = doctypesRes.rows.map((row: any) => row.definition as DocTypeDefinition);
+
+      const createdTables: string[] = [];
+
+      // Temporarily swap search_path to the new tenant schema to run table creations
+      await client.query(`SET search_path TO ${tenantId}, public`);
+
+      for (const doc of doctypes) {
+        const ddl = generateCreateTableDDL(doc);
+        for (const sql of ddl) {
+          await client.query(sql);
+        }
+        createdTables.push(doc.name);
+      }
+
+      return {
+        tenantId,
+        name,
+        domain,
+        createdTables
+      };
+    });
+
+    return c.json(output);
+  } catch (err: any) {
+    if (err.message.includes('Conflict:')) {
+      return c.json({ error: err.message }, 409);
+    }
+    console.error('Tenant registration failed:', err);
+    return c.json({ error: 'Failed to register tenant', details: err.message }, 500);
+  }
+});
+
+/**
+ * GET /api/meta/tenants
+ * List all registered tenants.
+ */
+metaRouter.get('/tenants', async (c) => {
+  try {
+    const res = await query('SELECT id, name, domain, created_at FROM _tenants ORDER BY id ASC');
+    return c.json(res.rows);
+  } catch (err: any) {
+    return c.json({ error: 'Failed to retrieve tenants', details: err.message }, 500);
+  }
+});
+
+/**
+ * GET /api/meta/doctypes
+ * List all definitions.
+ */
+metaRouter.get('/doctypes', async (c) => {
+  try {
+    const res = await query('SELECT name, created_at, updated_at FROM _doctype_meta ORDER BY name ASC');
+    return c.json(res.rows);
+  } catch (err: any) {
+    return c.json({ error: 'Failed to retrieve doctypes list', details: err.message }, 500);
+  }
+});
+
+/**
+ * GET /api/meta/doctypes/:name
+ * Retrieve specific definition metadata.
+ */
+metaRouter.get('/doctypes/:name', async (c) => {
+  const name = c.req.param('name');
+  const doc = await registry.get(name);
+  if (!doc) {
+    return c.json({ error: `DocType '${name}' not found` }, 404);
+  }
+  return c.json(doc);
+});

package/src/scheduler.ts

@@ -0,0 +1,118 @@
+import { query, withTransaction } from './db.js';
+
+export interface BackgroundTask {
+  name: string;
+  intervalSeconds: number;
+  execute: (client: any) => Promise<void>;
+}
+
+class AruviliScheduler {
+  private tasks: BackgroundTask[] = [];
+  private timer: any = null;
+  private isRunning = false;
+
+  /**
+   * Registers a task with the scheduler.
+   */
+  public register(task: BackgroundTask) {
+    this.tasks.push(task);
+  }
+
+  /**
+   * Starts the scheduler loop.
+   */
+  public async start(tickIntervalMs: number = 10000) {
+    if (this.isRunning) return;
+    this.isRunning = true;
+
+    // 1. Ensure the jobs tracking table exists
+    await query(`
+      CREATE TABLE IF NOT EXISTS _scheduled_jobs (
+        name VARCHAR(255) PRIMARY KEY,
+        last_started TIMESTAMP WITH TIME ZONE,
+        last_completed TIMESTAMP WITH TIME ZONE,
+        status VARCHAR(50),
+        error_message TEXT
+      );
+    `);
+
+    console.log(`[SCHEDULER] Started scheduler with tick interval: ${tickIntervalMs}ms. Registered tasks: ${this.tasks.length}`);
+
+    // Run the scheduler tick loop
+    this.timer = setInterval(async () => {
+      await this.tick();
+    }, tickIntervalMs);
+  }
+
+  /**
+   * Stops the scheduler.
+   */
+  public stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.isRunning = false;
+    console.log('[SCHEDULER] Scheduler stopped.');
+  }
+
+  /**
+   * Performs a single scheduler loop check.
+   */
+  private async tick() {
+    for (const task of this.tasks) {
+      await this.runTaskDistributed(task);
+    }
+  }
+
+  /**
+   * Tries to lock and run a background task.
+   */
+  private async runTaskDistributed(task: BackgroundTask) {
+    try {
+      // Try to acquire distributed lock atomically
+      const acquired = await withTransaction(async (client) => {
+        const sql = `
+          INSERT INTO _scheduled_jobs (name, last_started, status)
+          VALUES ($1, NOW(), 'RUNNING')
+          ON CONFLICT (name) DO UPDATE
+          SET last_started = NOW(), status = 'RUNNING'
+          WHERE (_scheduled_jobs.status != 'RUNNING' AND _scheduled_jobs.last_started < NOW() - (INTERVAL '1 second' * $2))
+             OR (_scheduled_jobs.status = 'RUNNING' AND _scheduled_jobs.last_started < NOW() - (INTERVAL '1 second' * $2 * 2))
+          RETURNING 1;
+        `;
+        const res = await client.query(sql, [task.name, task.intervalSeconds]);
+        return res.rows.length > 0;
+      });
+
+      if (!acquired) {
+        return; // Lock not acquired (already running or completed too recently)
+      }
+
+      console.log(`[SCHEDULER] Running task: ${task.name}`);
+      const start = Date.now();
+      try {
+        await withTransaction(async (client) => {
+          await task.execute(client);
+        });
+
+        // Update task state on success
+        await query(
+          `UPDATE _scheduled_jobs SET last_completed = NOW(), status = 'SUCCESS', error_message = NULL WHERE name = $1`,
+          [task.name]
+        );
+        console.log(`[SCHEDULER] Task ${task.name} finished successfully in ${Date.now() - start}ms`);
+      } catch (err: any) {
+        console.error(`[SCHEDULER ERROR] Task ${task.name} failed:`, err.message);
+        await query(
+          `UPDATE _scheduled_jobs SET last_completed = NOW(), status = 'FAILED', error_message = $2 WHERE name = $1`,
+          [task.name, err.message]
+        );
+      }
+    } catch (err: any) {
+      // Catch db concurrency locking serialization or connection errors
+    }
+  }
+}
+
+export const scheduler = new AruviliScheduler();

package/src/utils/link-validator.d.ts

@@ -0,0 +1,7 @@
+import { DocTypeDefinition } from '@aruvili/core';
+/**
+ * Validates all Link field values exist in their target DocType tables.
+ * Prevents dangling references (foreign key integrity without DB-level FK constraints).
+ */
+export declare function validateLinks(definition: DocTypeDefinition, record: Record<string, any>, client: any): Promise<string[]>;
+//# sourceMappingURL=link-validator.d.ts.map

package/src/utils/link-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-validator.d.ts","sourceRoot":"","sources":["link-validator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAgB,MAAM,YAAY,CAAC;AAG7D;;;GAGG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,iBAAiB,EAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,GAAG,GACV,OAAO,CAAC,MAAM,EAAE,CAAC,CAiCnB"}

package/src/utils/link-validator.js

@@ -0,0 +1,33 @@
+import { getTableName } from '@meta/core';
+/**
+ * Validates all Link field values exist in their target DocType tables.
+ * Prevents dangling references (foreign key integrity without DB-level FK constraints).
+ */
+export async function validateLinks(definition, record, client) {
+    const errors = [];
+    const linkFields = definition.fields.filter(f => f.fieldtype === 'Link' && f.options && record[f.fieldname]);
+    for (const field of linkFields) {
+        const targetDocType = field.options;
+        const targetTable = getTableName(targetDocType);
+        const value = record[field.fieldname];
+        if (typeof value !== 'string' || value.trim() === '')
+            continue;
+        try {
+            const res = await client.query(`SELECT 1 FROM ${targetTable} WHERE name = $1 LIMIT 1`, [value]);
+            if (res.rows.length === 0) {
+                errors.push(`Link field '${field.fieldname}': value '${value}' does not exist in ${targetDocType}.`);
+            }
+        }
+        catch (err) {
+            // Table might not exist yet if DocType not registered
+            if (err.code === '42P01') { // undefined_table
+                errors.push(`Link field '${field.fieldname}': target DocType '${targetDocType}' table does not exist.`);
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=link-validator.js.map

package/src/utils/link-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-validator.js","sourceRoot":"","sources":["link-validator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,YAAY,EAAE,MAAM,YAAY,CAAC;AAG7D;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,UAA6B,EAC7B,MAA2B,EAC3B,MAAW;IAEX,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,MAAM,CACzC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,MAAM,IAAI,CAAC,CAAC,OAAO,IAAI,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAChE,CAAC;IAEF,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;QAC/B,MAAM,aAAa,GAAG,KAAK,CAAC,OAAQ,CAAC;QACrC,MAAM,WAAW,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;QAChD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAEtC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,SAAS;QAE/D,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,KAAK,CAC5B,iBAAiB,WAAW,0BAA0B,EACtD,CAAC,KAAK,CAAC,CACR,CAAC;YACF,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC1B,MAAM,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,SAAS,aAAa,KAAK,uBAAuB,aAAa,GAAG,CAAC,CAAC;YACvG,CAAC;QACH,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,sDAAsD;YACtD,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC,kBAAkB;gBAC5C,MAAM,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,SAAS,sBAAsB,aAAa,yBAAyB,CAAC,CAAC;YAC1G,CAAC;iBAAM,CAAC;gBACN,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/src/utils/link-validator.ts

@@ -0,0 +1,45 @@
+import { DocTypeDefinition, getTableName } from '@aruvili/core';
+import { registry } from '../registry.js';
+
+/**
+ * Validates all Link field values exist in their target DocType tables.
+ * Prevents dangling references (foreign key integrity without DB-level FK constraints).
+ */
+export async function validateLinks(
+  definition: DocTypeDefinition,
+  record: Record<string, any>,
+  client: any
+): Promise<string[]> {
+  const errors: string[] = [];
+
+  const linkFields = definition.fields.filter(
+    f => f.fieldtype === 'Link' && f.options && record[f.fieldname]
+  );
+
+  for (const field of linkFields) {
+    const targetDocType = field.options!;
+    const targetTable = getTableName(targetDocType);
+    const value = record[field.fieldname];
+
+    if (typeof value !== 'string' || value.trim() === '') continue;
+
+    try {
+      const res = await client.query(
+        `SELECT 1 FROM ${targetTable} WHERE name = $1 LIMIT 1`,
+        [value]
+      );
+      if (res.rows.length === 0) {
+        errors.push(`Link field '${field.fieldname}': value '${value}' does not exist in ${targetDocType}.`);
+      }
+    } catch (err: any) {
+      // Table might not exist yet if DocType not registered
+      if (err.code === '42P01') { // undefined_table
+        errors.push(`Link field '${field.fieldname}': target DocType '${targetDocType}' table does not exist.`);
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  return errors;
+}

package/src/utils/resolver.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Resolves all Link fields for a list of document records in a single batch, preventing N+1 queries.
+ */
+export declare function resolveLinkFields(doctypeName: string, records: any[]): Promise<any[]>;
+//# sourceMappingURL=resolver.d.ts.map

package/src/utils/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["resolver.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAyD3F"}