@aruvili/core 0.1.0

package/src/ddl.ts

@@ -0,0 +1,246 @@
+import { DocTypeDefinition, DocField, DatabaseColumnMeta } from './types/index.js';
+
+/**
+ * Whitelist-validates an identifier to prevent SQL injection via dynamic column/table names.
+ * Only allows lowercase alphanumeric characters and underscores.
+ */
+function sanitizeIdentifier(name: string): string {
+  const sanitized = name.replace(/[^a-z0-9_]/g, '');
+  if (sanitized !== name.toLowerCase().replace(/[^a-z0-9_]/g, '')) {
+    throw new Error(`Unsafe SQL identifier detected: '${name}'`);
+  }
+  return sanitized;
+}
+
+/**
+ * Maps the DocType FieldType to a PostgreSQL database column type.
+ */
+export function mapFieldToPostgresType(field: DocField): string {
+  switch (field.fieldtype) {
+    case 'Select':
+    case 'Link':
+      return `VARCHAR(${field.max_length || 255})`;
+    case 'Text':
+      return `VARCHAR(${field.max_length || 255})`;
+    case 'Small Text':
+      return 'TEXT';
+    case 'Long Text':
+      return 'TEXT';
+    case 'Int':
+      return 'INTEGER';
+    case 'Float':
+      return 'DOUBLE PRECISION';
+    case 'Check':
+      return 'BOOLEAN';
+    case 'Date':
+      return 'DATE';
+    case 'Datetime':
+      return 'TIMESTAMP WITH TIME ZONE';
+    case 'Currency':
+      return 'NUMERIC(18, 4)';
+    case 'Table':
+    case 'Table MultiSelect':
+      // Child tables do not create direct columns in parent tables.
+      return '';
+    default:
+      throw new Error(`Unsupported field type: ${(field as any).fieldtype}`);
+  }
+}
+
+/**
+ * Standardize table name for a DocType.
+ * Enforces whitelist-safe identifier generation to prevent SQL injection.
+ */
+export function getTableName(doctypeName: string): string {
+  const sanitized = doctypeName.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+  if (!sanitized || sanitized.length === 0) {
+    throw new Error(`Cannot generate table name from empty DocType name.`);
+  }
+  return `dt_${sanitized}`;
+}
+
+/**
+ * Builds a safe default value expression for SQL column definitions.
+ * Prevents SQL injection through default value interpolation.
+ */
+function buildDefaultClause(value: any): string {
+  if (value === undefined || value === null) return '';
+  
+  if (typeof value === 'string') {
+    // Escape single quotes to prevent SQL injection
+    const escaped = value.replace(/'/g, "''").replace(/\\/g, '\\\\');
+    // Reject values containing SQL comment sequences or semicolons
+    if (escaped.includes('--') || escaped.includes(';') || escaped.includes('/*')) {
+      throw new Error(`Unsafe default value detected: '${value}'`);
+    }
+    return ` DEFAULT '${escaped}'`;
+  }
+  if (typeof value === 'boolean') {
+    return ` DEFAULT ${value ? 'TRUE' : 'FALSE'}`;
+  }
+  if (typeof value === 'number') {
+    if (!isFinite(value)) {
+      throw new Error(`Default value must be a finite number, got: ${value}`);
+    }
+    return ` DEFAULT ${value}`;
+  }
+  return '';
+}
+
+/**
+ * Generate DDL statement to create a table for a DocType.
+ */
+export function generateCreateTableDDL(definition: DocTypeDefinition): string[] {
+  const tableName = getTableName(definition.name);
+  const statements: string[] = [];
+  const columns: string[] = [];
+
+  // Every table has a primary key name and a globally unique UUIDv4 identifier
+  columns.push('name VARCHAR(255) PRIMARY KEY');
+  columns.push('uuid UUID DEFAULT gen_random_uuid() UNIQUE NOT NULL');
+  
+  // Standard audit fields
+  columns.push('created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()');
+  columns.push('updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()');
+  columns.push('created_by VARCHAR(255)');
+  columns.push('modified_by VARCHAR(255)');
+  columns.push('docstatus INTEGER DEFAULT 0'); // 0: Draft, 1: Submitted, 2: Cancelled
+  columns.push('version INTEGER DEFAULT 1');   // Optimistic concurrency control
+
+  if (definition.is_submittable) {
+    columns.push('amended_from VARCHAR(255)');
+  }
+
+  if (definition.workflow) {
+    const wfCol = sanitizeIdentifier(definition.workflow.fieldname);
+    if (!definition.fields.some(f => f.fieldname === wfCol)) {
+      columns.push(`${wfCol} VARCHAR(255) DEFAULT '${definition.workflow.initial_state}'`);
+    }
+  }
+
+  // Relational structural columns for Child Tables
+  if (definition.istable) {
+    columns.push('parent VARCHAR(255) NOT NULL');
+    columns.push('parenttype VARCHAR(255) NOT NULL');
+    columns.push('parentfield VARCHAR(255) NOT NULL');
+    columns.push('idx INTEGER NOT NULL');
+  }
+
+  // Custom metadata fields
+  for (const field of definition.fields) {
+    const pgType = mapFieldToPostgresType(field);
+    if (!pgType) continue; // Skip non-column fields like Table
+
+    const safeFieldname = sanitizeIdentifier(field.fieldname);
+    let colDef = `${safeFieldname} ${pgType}`;
+    
+    if (field.required) {
+      colDef += ' NOT NULL';
+    }
+    if (field.unique) {
+      colDef += ' UNIQUE';
+    }
+    
+    colDef += buildDefaultClause(field.default);
+    columns.push(colDef);
+  }
+
+  statements.push(`CREATE TABLE ${tableName} (\n  ${columns.join(',\n  ')}\n);`);
+
+  // Add indexing statements
+  if (definition.istable) {
+    statements.push(`CREATE INDEX IF NOT EXISTS idx_${tableName}_parent ON ${tableName} (parent, parenttype);`);
+    statements.push(`CREATE INDEX IF NOT EXISTS idx_${tableName}_idx ON ${tableName} (idx);`);
+  }
+
+  // Always index docstatus for workflow queries
+  statements.push(`CREATE INDEX IF NOT EXISTS idx_${tableName}_docstatus ON ${tableName} (docstatus);`);
+  // Always index created_at for sorting
+  statements.push(`CREATE INDEX IF NOT EXISTS idx_${tableName}_created_at ON ${tableName} (created_at);`);
+
+  if (definition.is_submittable) {
+    statements.push(`CREATE INDEX IF NOT EXISTS idx_${tableName}_amended_from ON ${tableName} (amended_from);`);
+  }
+
+  if (definition.workflow) {
+    const wfCol = sanitizeIdentifier(definition.workflow.fieldname);
+    statements.push(`CREATE INDEX IF NOT EXISTS idx_${tableName}_${wfCol} ON ${tableName} (${wfCol});`);
+  }
+
+  for (const field of definition.fields) {
+    if (field.searchable || field.fieldtype === 'Link') {
+      const pgType = mapFieldToPostgresType(field);
+      if (pgType) {
+        const safeFieldname = sanitizeIdentifier(field.fieldname);
+        statements.push(`CREATE INDEX IF NOT EXISTS idx_${tableName}_${safeFieldname} ON ${tableName} (${safeFieldname});`);
+      }
+    }
+  }
+
+  return statements;
+}
+
+/**
+ * Compare DB catalog columns with schema definition, generating ADD COLUMN alterations.
+ * Implements strict additive-only migration. NEVER drops or renames columns.
+ */
+export function generateAlterTableDDL(
+  definition: DocTypeDefinition,
+  existingColumns: DatabaseColumnMeta[]
+): string[] {
+  const tableName = getTableName(definition.name);
+  const statements: string[] = [];
+
+  const existingNames = new Set(existingColumns.map(c => c.columnName.toLowerCase()));
+
+  // Ensure every table has a unique UUID column
+  if (!existingNames.has('uuid')) {
+    statements.push(`ALTER TABLE ${tableName} ADD COLUMN uuid UUID DEFAULT gen_random_uuid() UNIQUE NOT NULL`);
+  }
+
+  // Ensure submittable tables have amended_from column
+  if (definition.is_submittable && !existingNames.has('amended_from')) {
+    statements.push(`ALTER TABLE ${tableName} ADD COLUMN amended_from VARCHAR(255)`);
+    statements.push(`CREATE INDEX IF NOT EXISTS idx_${tableName}_amended_from ON ${tableName} (amended_from)`);
+  }
+
+  // Ensure workflow columns exist
+  if (definition.workflow) {
+    const wfCol = sanitizeIdentifier(definition.workflow.fieldname);
+    if (!existingNames.has(wfCol)) {
+      statements.push(`ALTER TABLE ${tableName} ADD COLUMN ${wfCol} VARCHAR(255) DEFAULT '${definition.workflow.initial_state}'`);
+      statements.push(`CREATE INDEX IF NOT EXISTS idx_${tableName}_${wfCol} ON ${tableName} (${wfCol})`);
+    }
+  }
+
+  for (const field of definition.fields) {
+    const pgType = mapFieldToPostgresType(field);
+    if (!pgType) continue; // Skip Table fields
+
+    const safeFieldname = sanitizeIdentifier(field.fieldname);
+
+    if (!existingNames.has(safeFieldname)) {
+      let colDef = `ALTER TABLE ${tableName} ADD COLUMN ${safeFieldname} ${pgType}`;
+      
+      const defaultClause = buildDefaultClause(field.default);
+      
+      if (field.required) {
+        // Must provide default when adding NOT NULL to populated table
+        if (defaultClause) {
+          colDef += defaultClause;
+        }
+        colDef += ' NOT NULL';
+      } else {
+        colDef += defaultClause;
+      }
+      
+      statements.push(colDef);
+
+      if (field.searchable || field.fieldtype === 'Link') {
+        statements.push(`CREATE INDEX IF NOT EXISTS idx_${tableName}_${safeFieldname} ON ${tableName} (${safeFieldname});`);
+      }
+    }
+  }
+
+  return statements;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './types/index.js';
+export * from './validation.js';
+export * from './ddl.js';

package/src/types/index.ts

@@ -0,0 +1,92 @@
+export type FieldType = 
+  | 'Select' 
+  | 'Text' 
+  | 'Small Text' 
+  | 'Long Text' 
+  | 'Int' 
+  | 'Float' 
+  | 'Check'             // Boolean
+  | 'Date' 
+  | 'Datetime' 
+  | 'Link'              // Reference to another DocType
+  | 'Currency'
+  | 'Table'             // Child Table (references a DocType with istable: true)
+  | 'Table MultiSelect';// Many-to-many relationship helper
+
+export interface DocField {
+  fieldname: string;    // Database column name (snake_case, unique within DocType)
+  label: string;        // Human-readable form label
+  fieldtype: FieldType;
+  required?: boolean;
+  unique?: boolean;
+  options?: string;     // For 'Select': comma-separated. For 'Link'/'Table': target DocType name
+  default?: any;
+  searchable?: boolean; // Index this field
+  read_only?: boolean;  // Cannot be modified after creation
+  hidden?: boolean;     // Not displayed in UI but stored in DB
+  max_length?: number;  // Override default VARCHAR length
+  min_value?: number;   // Min constraint for numeric types
+  max_value?: number;   // Max constraint for numeric types
+}
+
+export interface PermissionRule {
+  role: string;
+  create: boolean;
+  read: boolean;
+  update: boolean;
+  delete: boolean;
+  submit?: boolean;     // Can submit submittable documents (locks it)
+  cancel?: boolean;     // Can cancel submitted documents (reverts it)
+}
+
+export type NamingRule = 'Autoincrement' | 'UUID' | 'Expression' | 'NamingSeries';
+
+export interface WorkflowTransition {
+  state: string;           // Current state (e.g. "Draft")
+  action: string;          // Triggering action (e.g. "Approve")
+  next_state: string;      // Resulting state (e.g. "Approved")
+  allowed_roles: string[]; // Roles authorized to trigger this transition
+}
+
+export interface DocTypeWorkflow {
+  fieldname: string;       // Database column storing state (e.g. "workflow_state")
+  initial_state: string;   // Initial state value
+  transitions: WorkflowTransition[];
+}
+
+export interface DocTypeDefinition {
+  name: string;          // Unique name (e.g. "Customer", "Sales Invoice")
+  istable?: boolean;     // If true, this is a Child Table
+  is_submittable?: boolean; // If true, supports Submit/Cancel states
+  naming_rule?: NamingRule;
+  naming_series?: string; // E.g. "INV-.YYYY.-.#####" or "ACC-.#####"
+  title_field?: string;  // Field to display when resolving Link fields (defaults to "name")
+  track_changes?: boolean;  // Explicitly opt-in to audit tracking (default true)
+  max_attachments?: number; // Attachment limit
+  fields: DocField[];
+  permissions: PermissionRule[];
+  workflow?: DocTypeWorkflow;
+}
+
+export interface DatabaseColumnMeta {
+  columnName: string;
+  dataType: string;
+  isNullable: boolean;
+  characterMaximumLength: number | null;
+}
+
+/**
+ * Reserved SQL keywords that cannot be used as table or column identifiers.
+ */
+export const SQL_RESERVED_WORDS = new Set([
+  'select', 'insert', 'update', 'delete', 'drop', 'alter', 'create',
+  'table', 'index', 'from', 'where', 'join', 'order', 'group', 'having',
+  'limit', 'offset', 'union', 'all', 'and', 'or', 'not', 'null', 'true',
+  'false', 'primary', 'key', 'foreign', 'references', 'constraint',
+  'default', 'check', 'unique', 'cascade', 'set', 'into', 'values',
+  'returning', 'exists', 'between', 'like', 'in', 'is', 'as', 'on',
+  'begin', 'commit', 'rollback', 'grant', 'revoke', 'user', 'role',
+  'schema', 'database', 'trigger', 'function', 'procedure', 'view',
+  'sequence', 'serial', 'bigserial', 'text', 'integer', 'boolean',
+  'varchar', 'timestamp', 'date', 'numeric', 'uuid'
+]);

package/src/validation.ts

@@ -0,0 +1,170 @@
+import { DocTypeDefinition, SQL_RESERVED_WORDS } from './types/index.js';
+
+const RESERVED_FIELD_NAMES = new Set([
+  'name',
+  'uuid',
+  'created_at',
+  'updated_at',
+  'created_by',
+  'modified_by',
+  'docstatus',
+  'parent',
+  'parenttype',
+  'parentfield',
+  'idx'
+]);
+
+const VALID_FIELDNAME_REGEX = /^[a-z][a-z0-9_]*$/;
+const VALID_DOCTYPE_NAME_REGEX = /^[A-Za-z][A-Za-z0-9 _-]*$/;
+const MAX_DOCTYPE_NAME_LENGTH = 100;
+const MAX_FIELD_COUNT = 200;
+const MAX_FIELDNAME_LENGTH = 63; // PostgreSQL identifier limit
+
+/**
+ * Validates a DocTypeDefinition schema structure for database safety and logical compliance.
+ * Enterprise-grade: checks SQL injection vectors, PostgreSQL limits, and structural integrity.
+ */
+export function validateDocType(definition: DocTypeDefinition): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  // === DocType Name Validations ===
+  if (!definition.name || definition.name.trim() === '') {
+    errors.push('DocType name is required.');
+  } else {
+    if (definition.name.length > MAX_DOCTYPE_NAME_LENGTH) {
+      errors.push(`DocType name '${definition.name}' exceeds maximum length of ${MAX_DOCTYPE_NAME_LENGTH} characters.`);
+    }
+    if (!VALID_DOCTYPE_NAME_REGEX.test(definition.name)) {
+      errors.push(`DocType name '${definition.name}' contains invalid characters. Allowed: letters, digits, spaces, hyphens, underscores.`);
+    }
+    // Block SQL reserved words as DocType names (prevents injection via table names)
+    if (SQL_RESERVED_WORDS.has(definition.name.toLowerCase().trim())) {
+      errors.push(`DocType name '${definition.name}' is a reserved SQL keyword and cannot be used.`);
+    }
+  }
+
+  // === Fields Array ===
+  if (!definition.fields || !Array.isArray(definition.fields)) {
+    errors.push('DocType must contain an array of fields.');
+    return { valid: false, errors };
+  }
+
+  if (definition.fields.length > MAX_FIELD_COUNT) {
+    errors.push(`DocType '${definition.name}' exceeds maximum of ${MAX_FIELD_COUNT} fields.`);
+  }
+
+  const seenFields = new Set<string>();
+
+  for (const field of definition.fields) {
+    const { fieldname, fieldtype } = field;
+
+    // --- Fieldname presence ---
+    if (!fieldname || fieldname.trim() === '') {
+      errors.push(`Fieldname is missing for a field in ${definition.name}.`);
+      continue;
+    }
+
+    // --- Fieldname format ---
+    if (!VALID_FIELDNAME_REGEX.test(fieldname)) {
+      errors.push(
+        `Fieldname '${fieldname}' in ${definition.name} is invalid. It must be snake_case, start with a lowercase letter, and contain only lowercase letters, digits, and underscores.`
+      );
+    }
+
+    // --- Fieldname length (PostgreSQL limit) ---
+    if (fieldname.length > MAX_FIELDNAME_LENGTH) {
+      errors.push(`Fieldname '${fieldname}' exceeds PostgreSQL identifier limit of ${MAX_FIELDNAME_LENGTH} characters.`);
+    }
+
+    // --- Reserved names ---
+    if (RESERVED_FIELD_NAMES.has(fieldname)) {
+      errors.push(
+        `Fieldname '${fieldname}' in ${definition.name} is reserved by the framework database architecture.`
+      );
+    }
+
+    // --- SQL reserved words as column names ---
+    if (SQL_RESERVED_WORDS.has(fieldname.toLowerCase())) {
+      errors.push(
+        `Fieldname '${fieldname}' in ${definition.name} is a reserved SQL keyword and cannot be used as a column name.`
+      );
+    }
+
+    // --- Duplicates ---
+    if (seenFields.has(fieldname)) {
+      errors.push(`Duplicate fieldname '${fieldname}' declared in ${definition.name}.`);
+    }
+    seenFields.add(fieldname);
+
+    // --- Fieldtype presence ---
+    if (!fieldtype) {
+      errors.push(`Field '${fieldname}' is missing fieldtype in ${definition.name}.`);
+    }
+
+    // === Specific field validations ===
+    if (fieldtype === 'Select') {
+      if (!field.options || field.options.trim() === '') {
+        errors.push(`Select field '${fieldname}' in ${definition.name} requires options (comma-separated list).`);
+      }
+    }
+
+    if (fieldtype === 'Link' || fieldtype === 'Table') {
+      if (!field.options || field.options.trim() === '') {
+        errors.push(`Relationship field '${fieldname}' of type '${fieldtype}' in ${definition.name} requires target option.`);
+      }
+    }
+
+    // --- Numeric constraints validation ---
+    if (field.min_value !== undefined && field.max_value !== undefined) {
+      if (field.min_value > field.max_value) {
+        errors.push(`Field '${fieldname}' in ${definition.name}: min_value (${field.min_value}) cannot exceed max_value (${field.max_value}).`);
+      }
+    }
+
+    // --- max_length validation ---
+    if (field.max_length !== undefined) {
+      if (field.max_length <= 0 || field.max_length > 10485760) {
+        errors.push(`Field '${fieldname}' in ${definition.name}: max_length must be between 1 and 10485760.`);
+      }
+    }
+  }
+
+  // === Validate naming configuration ===
+  if (!definition.istable) {
+    const rule = definition.naming_rule || 'UUID';
+    if (rule === 'NamingSeries' && (!definition.naming_series || definition.naming_series.trim() === '')) {
+      errors.push(`DocType '${definition.name}' requires naming_series configuration if NamingSeries rule is selected.`);
+    }
+  }
+
+  // === Validate permissions structure ===
+  if (!definition.istable && (!definition.permissions || definition.permissions.length === 0)) {
+    errors.push(`DocType '${definition.name}' must define at least one permission rule (non-child tables require explicit access control).`);
+  }
+
+  if (definition.permissions) {
+    for (const perm of definition.permissions) {
+      if (!perm.role || perm.role.trim() === '') {
+        errors.push(`A permission rule in ${definition.name} is missing a role name.`);
+      }
+    }
+  }
+
+  // Validate submittable config
+  if (definition.is_submittable && definition.istable) {
+    errors.push(`DocType '${definition.name}' cannot be both a child table (istable) and submittable.`);
+  }
+
+  // Validate title_field references an existing field
+  if (definition.title_field) {
+    const fieldExists = definition.fields.some(f => f.fieldname === definition.title_field);
+    if (!fieldExists) {
+      errors.push(`title_field '${definition.title_field}' in ${definition.name} does not reference an existing field.`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/**/*.test.ts"]
+}