@objectql/types 1.8.4 → 1.9.0

package/dist/config.d.ts

@@ -20,9 +20,14 @@ export interface ObjectQLConfig {
      */
     packages?: string[];
     /**
-     * List of npm packages or presets to load.
+     * @deprecated Use 'modules' instead.
      */
     presets?: string[];
+    /**
+     * List of modules to load.
+     * Can be npm packages or local directories.
+     */
+    modules?: string[];
     /**
      * List of plugins to load.
      * Can be an instance of ObjectQLPlugin or a package name string.

package/dist/field.d.ts

@@ -157,13 +157,23 @@ export interface FieldConfig {
     ai_context?: ValidationAiContext;
     /** Dimension of the vector for 'vector' type fields. */
     dimension?: number;
-    /** Formula expression. */
+    /** Formula expression (for 'formula' type fields). */
     formula?: string;
+    /** Expected return data type for formula fields. */
+    data_type?: 'number' | 'text' | 'date' | 'datetime' | 'boolean' | 'currency' | 'percent';
+    /** Display format for formula results (e.g., "0.00", "YYYY-MM-DD"). */
+    format?: string;
+    /** Decimal precision for numeric formula results. */
+    precision?: number;
+    /** Treat blank/null as zero in formula calculations. */
+    blank_as_zero?: boolean;
+    /** Default value for null/undefined referenced fields in formulas. */
+    treat_blank_as?: string | number | boolean | Date | null;
     /** Object to summarize. */
     summary_object?: string;
     /** Field on the summary object. */
     summary_field?: string;
     /** Type of summary (count, sum, min, max, avg). */
     summary_type?: string;
-    filters?: any[];
+    filters?: unknown[];
 }

package/dist/formula.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Formula Engine Types
+ *
+ * Type definitions for the ObjectQL Formula Engine.
+ * Formulas are read-only calculated fields that derive values from other fields,
+ * related records, or system variables using JavaScript-style expressions.
+ *
+ * @see docs/spec/formula.md for complete specification
+ */
+import { ObjectQLError } from './api';
+/**
+ * Data types that formula expressions can return
+ */
+export type FormulaDataType = 'number' | 'text' | 'date' | 'datetime' | 'boolean' | 'currency' | 'percent';
+/**
+ * Valid formula return values based on data type
+ */
+export type FormulaValue = number | string | boolean | Date | null | undefined;
+/**
+ * Valid field values that can be used in formula expressions
+ */
+export type FormulaFieldValue = string | number | boolean | Date | null | undefined | FormulaFieldValue[] | {
+    [key: string]: FormulaFieldValue;
+};
+/**
+ * Configuration for a formula field
+ *
+ * Formula fields are defined in object metadata and evaluated at query time.
+ * They are never stored in the database.
+ */
+export interface FormulaFieldConfig {
+    /** Field type - must be 'formula' */
+    type: 'formula';
+    /** JavaScript expression to evaluate */
+    expression: string;
+    /** Expected return data type of the expression */
+    data_type: FormulaDataType;
+    /** Display label for UI */
+    label?: string;
+    /** Help text explaining the formula's purpose */
+    description?: string;
+    /** Display format for numbers/dates (e.g., "0.00", "YYYY-MM-DD") */
+    format?: string;
+    /** Decimal precision for numeric results */
+    precision?: number;
+    /** Treat blank/null as zero in calculations (default: false) */
+    blank_as_zero?: boolean;
+    /** Default value to use when referenced fields are null/undefined */
+    treat_blank_as?: FormulaValue;
+    /** AI-friendly context for understanding business intent */
+    ai_context?: FormulaAiContext;
+}
+/**
+ * AI context for formula fields
+ *
+ * Provides semantic information to help AI tools understand the
+ * business purpose and validation requirements of the formula.
+ */
+export interface FormulaAiContext {
+    /** Business intent behind the formula */
+    intent?: string;
+    /** Business rule description in natural language */
+    business_rule?: string;
+    /** Algorithm description for complex formulas */
+    algorithm?: string;
+    /** Example calculations with inputs and expected results */
+    examples?: FormulaExample[];
+    /** Test cases for validation */
+    test_cases?: FormulaTestCase[];
+    /** Validation notes or constraints */
+    validation_notes?: string;
+    /** References to external documentation */
+    references?: string[];
+}
+/**
+ * Example demonstrating formula behavior
+ */
+export interface FormulaExample {
+    /** Description of this example */
+    description: string;
+    /** Input field values */
+    inputs: Record<string, FormulaFieldValue>;
+    /** Expected result */
+    result: FormulaValue;
+    /** Optional explanation of the calculation */
+    explanation?: string;
+}
+/**
+ * Test case for formula validation
+ */
+export interface FormulaTestCase {
+    /** Test case description */
+    description?: string;
+    /** Input values for the test */
+    input: Record<string, FormulaFieldValue>;
+    /** Expected output value */
+    expected: FormulaValue;
+    /** Whether this test should pass or fail */
+    should_pass?: boolean;
+}
+/**
+ * Runtime context for formula evaluation
+ *
+ * Provides access to record data, system variables, and user context
+ * during formula expression evaluation.
+ */
+export interface FormulaContext {
+    /** Current record data with all field values */
+    record: Record<string, FormulaFieldValue>;
+    /** System date/time variables */
+    system: FormulaSystemVariables;
+    /** Current user context */
+    current_user: FormulaUserContext;
+    /** Record context flags */
+    is_new: boolean;
+    /** Record ID (if exists) */
+    record_id?: string;
+}
+/**
+ * System variables available in formula expressions
+ */
+export interface FormulaSystemVariables {
+    /** Current date (YYYY-MM-DD) */
+    today: Date;
+    /** Current timestamp */
+    now: Date;
+    /** Current year */
+    year: number;
+    /** Current month (1-12) */
+    month: number;
+    /** Current day of month (1-31) */
+    day: number;
+    /** Current hour (0-23) */
+    hour: number;
+    /** Current minute (0-59) */
+    minute?: number;
+    /** Current second (0-59) */
+    second?: number;
+}
+/**
+ * Current user context available in formula expressions
+ */
+export interface FormulaUserContext {
+    /** User ID */
+    id: string;
+    /** User's display name */
+    name?: string;
+    /** User's email address */
+    email?: string;
+    /** User's role */
+    role?: string;
+    /** Additional user properties */
+    [key: string]: unknown;
+}
+/**
+ * Result of formula evaluation
+ */
+export interface FormulaEvaluationResult {
+    /** Computed value */
+    value: FormulaValue;
+    /** Data type of the result */
+    type: FormulaDataType;
+    /** Whether evaluation was successful */
+    success: boolean;
+    /** Error message if evaluation failed */
+    error?: string;
+    /** Stack trace for debugging (if error occurred) */
+    stack?: string;
+    /** Execution time in milliseconds */
+    execution_time?: number;
+}
+/**
+ * Error types that can occur during formula evaluation
+ */
+export declare enum FormulaErrorType {
+    /** Syntax error in the expression */
+    SYNTAX_ERROR = "SYNTAX_ERROR",
+    /** Referenced field does not exist */
+    FIELD_NOT_FOUND = "FIELD_NOT_FOUND",
+    /** Type mismatch in operation */
+    TYPE_ERROR = "TYPE_ERROR",
+    /** Division by zero */
+    DIVISION_BY_ZERO = "DIVISION_BY_ZERO",
+    /** Null or undefined value in operation */
+    NULL_REFERENCE = "NULL_REFERENCE",
+    /** Evaluation timeout */
+    TIMEOUT = "TIMEOUT",
+    /** Security violation (restricted operation) */
+    SECURITY_VIOLATION = "SECURITY_VIOLATION",
+    /** Generic runtime error */
+    RUNTIME_ERROR = "RUNTIME_ERROR"
+}
+/**
+ * Context information for formula errors
+ */
+export interface FormulaErrorContext {
+    /** The formula expression that caused the error */
+    expression?: string;
+    /** Field name if applicable */
+    field?: string;
+    /** Record data at time of error */
+    record?: Record<string, FormulaFieldValue>;
+    /** Additional context information */
+    [key: string]: unknown;
+}
+/**
+ * Custom error for formula evaluation failures
+ * Extends ObjectQLError to maintain consistency with ObjectQL error handling
+ */
+export declare class FormulaError extends ObjectQLError {
+    readonly errorType: FormulaErrorType;
+    readonly expression?: string;
+    readonly errorContext?: FormulaErrorContext;
+    constructor(type: FormulaErrorType, message: string, expression?: string, context?: FormulaErrorContext);
+}
+/**
+ * Options for formula evaluation
+ */
+export interface FormulaEvaluationOptions {
+    /** Maximum execution time in milliseconds (default: 1000) */
+    timeout?: number;
+    /** Enable strict mode (default: true) */
+    strict?: boolean;
+    /** Enable debug mode with detailed logging */
+    debug?: boolean;
+    /** Allow async operations (default: false) */
+    allow_async?: boolean;
+    /** Sandbox restrictions */
+    sandbox?: {
+        /** Allowed global variables */
+        allowed_globals?: string[];
+        /** Blocked operations/methods */
+        blocked_operations?: string[];
+    };
+}
+/**
+ * Metadata about a formula field for introspection
+ */
+export interface FormulaMetadata {
+    /** Formula field name */
+    field_name: string;
+    /** The formula expression */
+    expression: string;
+    /** Expected return type */
+    data_type: FormulaDataType;
+    /** Fields referenced in the expression */
+    dependencies: string[];
+    /** Lookup chains used (e.g., ["account.owner.name"]) */
+    lookup_chains: string[];
+    /** System variables used */
+    system_variables: string[];
+    /** Whether the formula is valid */
+    is_valid: boolean;
+    /** Validation errors if invalid */
+    validation_errors?: string[];
+    /** Estimated complexity (simple, medium, complex) */
+    complexity?: 'simple' | 'medium' | 'complex';
+}
+/**
+ * Statistics about formula execution
+ */
+export interface FormulaExecutionStats {
+    /** Formula field name */
+    field_name: string;
+    /** Total number of evaluations */
+    evaluation_count: number;
+    /** Number of successful evaluations */
+    success_count: number;
+    /** Number of failed evaluations */
+    error_count: number;
+    /** Average execution time in milliseconds */
+    avg_execution_time: number;
+    /** Maximum execution time in milliseconds */
+    max_execution_time: number;
+    /** Minimum execution time in milliseconds */
+    min_execution_time: number;
+    /** Most common error types */
+    common_errors?: Record<FormulaErrorType, number>;
+}
+/**
+ * Type for custom formula functions
+ * These functions can be registered in the formula engine for use in expressions
+ */
+export type FormulaCustomFunction = (...args: FormulaFieldValue[]) => FormulaValue;
+/**
+ * Configuration for formula engine
+ */
+export interface FormulaEngineConfig {
+    /** Enable formula caching */
+    enable_cache?: boolean;
+    /** Cache TTL in seconds */
+    cache_ttl?: number;
+    /** Maximum formula execution time in milliseconds */
+    max_execution_time?: number;
+    /** Enable performance monitoring */
+    enable_monitoring?: boolean;
+    /** Custom function library */
+    custom_functions?: Record<string, FormulaCustomFunction>;
+    /** Sandbox configuration */
+    sandbox?: {
+        /** Enable sandbox mode */
+        enabled?: boolean;
+        /** Allowed global objects */
+        allowed_globals?: string[];
+        /** Blocked operations */
+        blocked_operations?: string[];
+    };
+}

package/dist/formula.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Formula Engine Types
+ *
+ * Type definitions for the ObjectQL Formula Engine.
+ * Formulas are read-only calculated fields that derive values from other fields,
+ * related records, or system variables using JavaScript-style expressions.
+ *
+ * @see docs/spec/formula.md for complete specification
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FormulaError = exports.FormulaErrorType = void 0;
+const api_1 = require("./api");
+/**
+ * Error types that can occur during formula evaluation
+ */
+var FormulaErrorType;
+(function (FormulaErrorType) {
+    /** Syntax error in the expression */
+    FormulaErrorType["SYNTAX_ERROR"] = "SYNTAX_ERROR";
+    /** Referenced field does not exist */
+    FormulaErrorType["FIELD_NOT_FOUND"] = "FIELD_NOT_FOUND";
+    /** Type mismatch in operation */
+    FormulaErrorType["TYPE_ERROR"] = "TYPE_ERROR";
+    /** Division by zero */
+    FormulaErrorType["DIVISION_BY_ZERO"] = "DIVISION_BY_ZERO";
+    /** Null or undefined value in operation */
+    FormulaErrorType["NULL_REFERENCE"] = "NULL_REFERENCE";
+    /** Evaluation timeout */
+    FormulaErrorType["TIMEOUT"] = "TIMEOUT";
+    /** Security violation (restricted operation) */
+    FormulaErrorType["SECURITY_VIOLATION"] = "SECURITY_VIOLATION";
+    /** Generic runtime error */
+    FormulaErrorType["RUNTIME_ERROR"] = "RUNTIME_ERROR";
+})(FormulaErrorType || (exports.FormulaErrorType = FormulaErrorType = {}));
+/**
+ * Custom error for formula evaluation failures
+ * Extends ObjectQLError to maintain consistency with ObjectQL error handling
+ */
+class FormulaError extends api_1.ObjectQLError {
+    constructor(type, message, expression, context) {
+        super({
+            code: type,
+            message,
+            details: {
+                formula_error_type: type,
+                expression,
+                ...context
+            }
+        });
+        this.name = 'FormulaError';
+        this.errorType = type;
+        this.expression = expression;
+        this.errorContext = context;
+    }
+}
+exports.FormulaError = FormulaError;
+//# sourceMappingURL=formula.js.map

package/dist/formula.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formula.js","sourceRoot":"","sources":["../src/formula.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH,+BAAoD;AA0OpD;;GAEG;AACH,IAAY,gBAwBX;AAxBD,WAAY,gBAAgB;IACxB,qCAAqC;IACrC,iDAA6B,CAAA;IAE7B,sCAAsC;IACtC,uDAAmC,CAAA;IAEnC,iCAAiC;IACjC,6CAAyB,CAAA;IAEzB,uBAAuB;IACvB,yDAAqC,CAAA;IAErC,2CAA2C;IAC3C,qDAAiC,CAAA;IAEjC,yBAAyB;IACzB,uCAAmB,CAAA;IAEnB,gDAAgD;IAChD,6DAAyC,CAAA;IAEzC,4BAA4B;IAC5B,mDAA+B,CAAA;AACnC,CAAC,EAxBW,gBAAgB,gCAAhB,gBAAgB,QAwB3B;AAmBD;;;GAGG;AACH,MAAa,YAAa,SAAQ,mBAAa;IAK3C,YACI,IAAsB,EACtB,OAAe,EACf,UAAmB,EACnB,OAA6B;QAE7B,KAAK,CAAC;YACF,IAAI,EAAE,IAAc;YACpB,OAAO;YACP,OAAO,EAAE;gBACL,kBAAkB,EAAE,IAAI;gBACxB,UAAU;gBACV,GAAG,OAAO;aACb;SACJ,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC;IAChC,CAAC;CACJ;AAzBD,oCAyBC"}

package/dist/index.d.ts

@@ -22,3 +22,4 @@ export * from './view';
 export * from './workflow';
 export * from './report';
 export * from './form';
+export * from './formula';

package/dist/index.js

@@ -38,4 +38,5 @@ __exportStar(require("./view"), exports);
 __exportStar(require("./workflow"), exports);
 __exportStar(require("./report"), exports);
 __exportStar(require("./form"), exports);
+__exportStar(require("./formula"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,2CAAyB;AACzB,2CAAyB;AACzB,0CAAwB;AACxB,6CAA2B;AAC3B,yCAAuB;AACvB,2CAAyB;AACzB,+CAA6B;AAC7B,wCAAsB;AACtB,2CAAyB;AACzB,2CAAyB;AACzB,4CAA0B;AAC1B,+CAA6B;AAC7B,+CAA6B;AAC7B,yCAAuB;AACvB,2CAAyB;AACzB,gDAA8B;AAC9B,yCAAuB;AACvB,8CAA4B;AAC5B,wCAAsB;AACtB,yCAAuB;AACvB,6CAA2B;AAC3B,2CAAyB;AACzB,yCAAuB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,2CAAyB;AACzB,2CAAyB;AACzB,0CAAwB;AACxB,6CAA2B;AAC3B,yCAAuB;AACvB,2CAAyB;AACzB,+CAA6B;AAC7B,wCAAsB;AACtB,2CAAyB;AACzB,2CAAyB;AACzB,4CAA0B;AAC1B,+CAA6B;AAC7B,+CAA6B;AAC7B,yCAAuB;AACvB,2CAAyB;AACzB,gDAA8B;AAC9B,yCAAuB;AACvB,8CAA4B;AAC5B,wCAAsB;AACtB,yCAAuB;AACvB,6CAA2B;AAC3B,2CAAyB;AACzB,yCAAuB;AACvB,4CAA0B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectql/types",
-  "version": "1.8.4",
+  "version": "1.9.0",
   "description": "Pure TypeScript type definitions and interfaces for the ObjectQL protocol - The Contract",
   "keywords": [
     "objectql",

package/schemas/object.schema.json

@@ -559,6 +559,23 @@
           "$ref": "#/definitions/ValidationAiContext",
           "description": "AI context for the field. Provides semantic information for AI tools."
         },
+        "blank_as_zero": {
+          "description": "Treat blank/null as zero in formula calculations.",
+          "type": "boolean"
+        },
+        "data_type": {
+          "description": "Expected return data type for formula fields.",
+          "enum": [
+            "number",
+            "text",
+            "date",
+            "datetime",
+            "boolean",
+            "currency",
+            "percent"
+          ],
+          "type": "string"
+        },
         "defaultValue": {
           "description": "The default value if not provided during creation."
         },
@@ -574,8 +591,12 @@
           "items": {},
           "type": "array"
         },
+        "format": {
+          "description": "Display format for formula results (e.g., \"0.00\", \"YYYY-MM-DD\").",
+          "type": "string"
+        },
         "formula": {
-          "description": "Formula expression.",
+          "description": "Formula expression (for 'formula' type fields).",
           "type": "string"
         },
         "help_text": {
@@ -649,6 +670,10 @@
           },
           "type": "array"
         },
+        "precision": {
+          "description": "Decimal precision for numeric formula results.",
+          "type": "number"
+        },
         "readonly": {
           "description": "Whether the field is read-only in UI.",
           "type": "boolean"
@@ -677,6 +702,27 @@
           "description": "Type of summary (count, sum, min, max, avg).",
           "type": "string"
         },
+        "treat_blank_as": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "number"
+            },
+            {
+              "type": "boolean"
+            },
+            {
+              "format": "date-time",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Default value for null/undefined referenced fields in formulas."
+        },
         "type": {
           "$ref": "#/definitions/FieldType",
           "description": "The data type of the field."