@api-client/core 0.18.24 → 0.18.26

package/build/src/modeling/Semantics.js

@@ -169,6 +169,12 @@ export var SemanticType;
      * Annotates a field as derived from other fields.
      */
     SemanticType["Derived"] = "Semantic#Derived";
+    /**
+     * Annotates a field that should automatically receive the client's IP address.
+     * The runtime automatically populates this field with the request's IP address
+     * when creating or updating records, providing audit trail and geolocation capabilities.
+     */
+    SemanticType["ClientIPAddress"] = "Semantic#ClientIPAddress";
     //
     // Association-Level Semantics
     //
@@ -254,6 +260,100 @@ export var SemanticCategory;
      */
     SemanticCategory["Computed"] = "Computed Values";
 })(SemanticCategory || (SemanticCategory = {}));
+/**
+ * Defines when a semantic should execute in relation to database operations.
+ */
+export var SemanticTiming;
+(function (SemanticTiming) {
+    /**
+     * Execute before the database operation (validation, preprocessing)
+     */
+    SemanticTiming["Before"] = "Before";
+    /**
+     * Execute after the database operation (cleanup, notifications, derived values)
+     */
+    SemanticTiming["After"] = "After";
+    /**
+     * Execute both before and after the operation
+     */
+    SemanticTiming["Both"] = "Both";
+    /**
+     * No automatic execution (manual/on-demand only)
+     */
+    SemanticTiming["None"] = "None";
+})(SemanticTiming || (SemanticTiming = {}));
+/**
+ * Defines which database operations can trigger a semantic.
+ */
+export var SemanticOperation;
+(function (SemanticOperation) {
+    SemanticOperation["Create"] = "Create";
+    SemanticOperation["Read"] = "Read";
+    SemanticOperation["Update"] = "Update";
+    SemanticOperation["Delete"] = "Delete";
+    /**
+     * Special operation for list/query operations
+     */
+    SemanticOperation["List"] = "List";
+})(SemanticOperation || (SemanticOperation = {}));
+/**
+ * Defines the execution mode for a semantic.
+ */
+export var SemanticExecutionMode;
+(function (SemanticExecutionMode) {
+    /**
+     * Execute synchronously as part of the main operation
+     */
+    SemanticExecutionMode["Synchronous"] = "Synchronous";
+    /**
+     * Execute asynchronously after the main operation
+     */
+    SemanticExecutionMode["Asynchronous"] = "Asynchronous";
+    /**
+     * Execute in background/queue (fire and forget)
+     */
+    SemanticExecutionMode["Background"] = "Background";
+})(SemanticExecutionMode || (SemanticExecutionMode = {}));
+/**
+ * Defines validation strategies for semantics.
+ */
+export var SemanticValidationStrategy;
+(function (SemanticValidationStrategy) {
+    /**
+     * Fail the operation if semantic validation fails
+     */
+    SemanticValidationStrategy["Strict"] = "Strict";
+    /**
+     * Log warnings but continue operation
+     */
+    SemanticValidationStrategy["Warning"] = "Warning";
+    /**
+     * Skip validation entirely
+     */
+    SemanticValidationStrategy["Skip"] = "Skip";
+})(SemanticValidationStrategy || (SemanticValidationStrategy = {}));
+/**
+ * Defines caching strategies for computed semantics.
+ */
+export var SemanticCacheStrategy;
+(function (SemanticCacheStrategy) {
+    /**
+     * No caching - always compute
+     */
+    SemanticCacheStrategy["None"] = "None";
+    /**
+     * Cache until dependent fields change
+     */
+    SemanticCacheStrategy["Dependency"] = "Dependency";
+    /**
+     * Cache with TTL expiration
+     */
+    SemanticCacheStrategy["TimeToLive"] = "TimeToLive";
+    /**
+     * Cache until manually invalidated
+     */
+    SemanticCacheStrategy["Manual"] = "Manual";
+})(SemanticCacheStrategy || (SemanticCacheStrategy = {}));
 /**
  * A type guard to check if a semantic is an EntitySemantic.
  */
@@ -281,6 +381,10 @@ export const DataSemantics = {
         description: 'System users and accounts',
         category: SemanticCategory.Identity,
         hasConfig: false,
+        runtime: {
+            timing: SemanticTiming.None,
+            operations: [],
+        },
     },
     [SemanticType.Password]: {
         id: SemanticType.Password,
@@ -290,6 +394,19 @@ export const DataSemantics = {
         category: SemanticCategory.Identity,
         applicableDataTypes: ['string'],
         hasConfig: true,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Create, SemanticOperation.Update],
+            priority: 10, // High priority for security
+            canDisable: false, // Security semantics cannot be disabled
+            timeoutMs: 2000, // Allow time for hashing
+            conditions: [
+                {
+                    expression: 'entity[semantics.Password] != null && entity[semantics.Password].length > 0',
+                    description: 'Only process when password field has a value',
+                },
+            ],
+        },
     },
     [SemanticType.UserRole]: {
         id: SemanticType.UserRole,
@@ -299,6 +416,17 @@ export const DataSemantics = {
         category: SemanticCategory.Identity,
         applicableDataTypes: ['string'],
         hasConfig: false,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [
+                SemanticOperation.Create,
+                SemanticOperation.Read,
+                SemanticOperation.Update,
+                SemanticOperation.Delete,
+                SemanticOperation.List,
+            ],
+            priority: 20,
+        },
     },
     [SemanticType.ResourceOwnerIdentifier]: {
         id: SemanticType.ResourceOwnerIdentifier,
@@ -307,6 +435,18 @@ export const DataSemantics = {
         description: 'Links record to owner user',
         category: SemanticCategory.Identity,
         hasConfig: false,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [
+                SemanticOperation.Create,
+                SemanticOperation.Read,
+                SemanticOperation.Update,
+                SemanticOperation.Delete,
+                SemanticOperation.List,
+            ],
+            priority: 5, // Very high priority for access control
+            canDisable: false,
+        },
     },
     //
     // Timestamps & Versioning
@@ -319,6 +459,18 @@ export const DataSemantics = {
         category: SemanticCategory.Lifecycle,
         applicableDataTypes: ['datetime'],
         hasConfig: false,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Create],
+            priority: 90,
+            timeoutMs: 100, // Very fast operation
+            conditions: [
+                {
+                    expression: 'entity[semantics.CreatedTimestamp] == null',
+                    description: 'Only set timestamp if not already provided',
+                },
+            ],
+        },
     },
     [SemanticType.UpdatedTimestamp]: {
         id: SemanticType.UpdatedTimestamp,
@@ -328,6 +480,11 @@ export const DataSemantics = {
         category: SemanticCategory.Lifecycle,
         applicableDataTypes: ['datetime'],
         hasConfig: false,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Update],
+            priority: 90,
+        },
     },
     [SemanticType.DeletedTimestamp]: {
         id: SemanticType.DeletedTimestamp,
@@ -337,6 +494,11 @@ export const DataSemantics = {
         category: SemanticCategory.Lifecycle,
         applicableDataTypes: ['datetime'],
         hasConfig: false,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Delete],
+            priority: 80,
+        },
     },
     [SemanticType.DeletedFlag]: {
         id: SemanticType.DeletedFlag,
@@ -346,6 +508,11 @@ export const DataSemantics = {
         category: SemanticCategory.Lifecycle,
         applicableDataTypes: ['boolean'],
         hasConfig: false,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Delete, SemanticOperation.Read, SemanticOperation.List],
+            priority: 80,
+        },
     },
     [SemanticType.Version]: {
         id: SemanticType.Version,
@@ -355,6 +522,11 @@ export const DataSemantics = {
         category: SemanticCategory.Lifecycle,
         applicableDataTypes: ['number'],
         hasConfig: false,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Update],
+            priority: 85,
+        },
     },
     //
     // Content & Media
@@ -367,6 +539,10 @@ export const DataSemantics = {
         category: SemanticCategory.Content,
         applicableDataTypes: ['string'],
         hasConfig: false,
+        runtime: {
+            timing: SemanticTiming.None,
+            operations: [],
+        },
     },
     [SemanticType.Description]: {
         id: SemanticType.Description,
@@ -376,6 +552,10 @@ export const DataSemantics = {
         category: SemanticCategory.Content,
         applicableDataTypes: ['string'],
         hasConfig: false,
+        runtime: {
+            timing: SemanticTiming.None,
+            operations: [],
+        },
     },
     [SemanticType.Summary]: {
         id: SemanticType.Summary,
@@ -385,6 +565,10 @@ export const DataSemantics = {
         category: SemanticCategory.Content,
         applicableDataTypes: ['string'],
         hasConfig: false,
+        runtime: {
+            timing: SemanticTiming.None,
+            operations: [],
+        },
     },
     [SemanticType.Markdown]: {
         id: SemanticType.Markdown,
@@ -394,6 +578,11 @@ export const DataSemantics = {
         category: SemanticCategory.Content,
         applicableDataTypes: ['string'],
         hasConfig: true,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Create, SemanticOperation.Update],
+            priority: 50, // Process before storage
+        },
     },
     [SemanticType.HTML]: {
         id: SemanticType.HTML,
@@ -403,6 +592,11 @@ export const DataSemantics = {
         category: SemanticCategory.Content,
         applicableDataTypes: ['string'],
         hasConfig: true,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Create, SemanticOperation.Update],
+            priority: 50, // Process before storage for sanitization
+        },
     },
     [SemanticType.ImageURL]: {
         id: SemanticType.ImageURL,
@@ -412,6 +606,11 @@ export const DataSemantics = {
         category: SemanticCategory.Content,
         applicableDataTypes: ['string'],
         hasConfig: false,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Create, SemanticOperation.Update],
+            priority: 60, // Validate URLs before storage
+        },
     },
     [SemanticType.FileURL]: {
         id: SemanticType.FileURL,
@@ -421,6 +620,11 @@ export const DataSemantics = {
         category: SemanticCategory.Content,
         applicableDataTypes: ['string'],
         hasConfig: false,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Create, SemanticOperation.Update],
+            priority: 60, // Validate URLs before storage
+        },
     },
     //
     // Business Data
@@ -433,6 +637,11 @@ export const DataSemantics = {
         category: SemanticCategory.Business,
         applicableDataTypes: ['string'],
         hasConfig: true,
+        runtime: {
+            timing: SemanticTiming.Both,
+            operations: [SemanticOperation.Create, SemanticOperation.Update, SemanticOperation.Read, SemanticOperation.List],
+            priority: 30, // Validate state transitions before, filter by state after
+        },
     },
     [SemanticType.Currency]: {
         id: SemanticType.Currency,
@@ -442,6 +651,11 @@ export const DataSemantics = {
         category: SemanticCategory.Business,
         applicableDataTypes: ['number', 'string'],
         hasConfig: true,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Create, SemanticOperation.Update],
+            priority: 70, // Validate currency format and precision
+        },
     },
     [SemanticType.SKU]: {
         id: SemanticType.SKU,
@@ -451,6 +665,11 @@ export const DataSemantics = {
         category: SemanticCategory.Business,
         applicableDataTypes: ['string'],
         hasConfig: true,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Create, SemanticOperation.Update],
+            priority: 25, // High priority for uniqueness validation
+        },
     },
     //
     // Contact Information
@@ -463,6 +682,11 @@ export const DataSemantics = {
         category: SemanticCategory.Contact,
         applicableDataTypes: ['string'],
         hasConfig: true,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Create, SemanticOperation.Update],
+            priority: 40, // Validate email format
+        },
     },
     [SemanticType.Phone]: {
         id: SemanticType.Phone,
@@ -472,6 +696,11 @@ export const DataSemantics = {
         category: SemanticCategory.Contact,
         applicableDataTypes: ['string'],
         hasConfig: true,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Create, SemanticOperation.Update],
+            priority: 40, // Validate phone format
+        },
     },
     [SemanticType.URL]: {
         id: SemanticType.URL,
@@ -481,6 +710,32 @@ export const DataSemantics = {
         category: SemanticCategory.Contact,
         applicableDataTypes: ['string'],
         hasConfig: true,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Create, SemanticOperation.Update],
+            priority: 40, // Validate URL format
+        },
+    },
+    [SemanticType.ClientIPAddress]: {
+        id: SemanticType.ClientIPAddress,
+        displayName: 'Client IP Address',
+        scope: SemanticScope.Property,
+        description: 'Automatically populated client IP address',
+        category: SemanticCategory.Contact,
+        applicableDataTypes: ['string'],
+        hasConfig: false,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Create, SemanticOperation.Update],
+            priority: 95, // Low priority, populate after other validations
+            timeoutMs: 100, // Very fast operation
+            conditions: [
+                {
+                    expression: 'entity[semantics.ClientIPAddress] == null',
+                    description: 'Only set IP address if not already provided',
+                },
+            ],
+        },
     },
     //
     // Classification & Organization
@@ -493,6 +748,23 @@ export const DataSemantics = {
         category: SemanticCategory.Organization,
         applicableDataTypes: ['string'],
         hasConfig: true,
+        runtime: {
+            timing: SemanticTiming.Before,
+            operations: [SemanticOperation.Create, SemanticOperation.Update],
+            priority: 30, // Generate slug from title, validate uniqueness
+            timeoutMs: 1000,
+            conditions: [
+                {
+                    expression: 'entity[semantics.PublicUniqueName] == null || entity[semantics.PublicUniqueName].length == 0',
+                    description: 'Only generate slug if not already provided',
+                },
+                // Let's not guess which field is marked as slug source in the `PublicUniqueName` configuration.
+                // {
+                //   expression: 'entity[semantics.Title] != null && entity[semantics.Title].length > 0',
+                //   description: 'Only generate slug if title field exists and has content',
+                // },
+            ],
+        },
     },
     [SemanticType.Tags]: {
         id: SemanticType.Tags,
@@ -501,6 +773,11 @@ export const DataSemantics = {
         description: 'Enable tagging functionality',
         category: SemanticCategory.Organization,
         hasConfig: true,
+        runtime: {
+            timing: SemanticTiming.After,
+            operations: [SemanticOperation.Create, SemanticOperation.Update, SemanticOperation.Delete],
+            priority: 200, // Process after main operation
+        },
     },
     [SemanticType.Categories]: {
         id: SemanticType.Categories,
@@ -509,6 +786,11 @@ export const DataSemantics = {
         description: 'Enable categorization functionality',
         category: SemanticCategory.Organization,
         hasConfig: true,
+        runtime: {
+            timing: SemanticTiming.After,
+            operations: [SemanticOperation.Create, SemanticOperation.Update, SemanticOperation.Delete],
+            priority: 200, // Process after main operation
+        },
     },
     //
     // Location & Geography
@@ -521,6 +803,11 @@ export const DataSemantics = {
         category: SemanticCategory.Location,
         applicableDataTypes: ['string'],
         hasConfig: true,
+        runtime: {
+            timing: SemanticTiming.Both,
+            operations: [SemanticOperation.Create, SemanticOperation.Update, SemanticOperation.Read, SemanticOperation.List],
+            priority: 60, // Validate coordinates before, enable spatial queries after
+        },
     },
     //
     // Computed Values
@@ -534,6 +821,11 @@ export const DataSemantics = {
         category: SemanticCategory.Computed,
         applicableDataTypes: ['string', 'number', 'boolean', 'date', 'datetime', 'time', 'binary'],
         hasConfig: true,
+        runtime: {
+            timing: SemanticTiming.Both,
+            operations: [SemanticOperation.Create, SemanticOperation.Update, SemanticOperation.Read],
+            priority: 150, // Calculate after other validations, recalculate on read if needed
+        },
     },
     [SemanticType.Derived]: {
         id: SemanticType.Derived,
@@ -543,8 +835,44 @@ export const DataSemantics = {
         category: SemanticCategory.Computed,
         applicableDataTypes: ['string'],
         hasConfig: true,
+        runtime: {
+            timing: SemanticTiming.After,
+            operations: [SemanticOperation.Create, SemanticOperation.Update],
+            priority: 180, // Derive after all other processing
+        },
     },
 };
+/**
+ * Get all semantics that should run for a specific operation and timing
+ */
+export function getSemanticsForOperation(semantics, operation, timing) {
+    return semantics
+        .filter((semantic) => {
+        const definition = DataSemantics[semantic.id];
+        if (!definition?.runtime) {
+            return false;
+        }
+        const { timing: semanticTiming, operations } = definition.runtime;
+        // Check if timing matches
+        const timingMatches = semanticTiming === timing || semanticTiming === SemanticTiming.Both;
+        // Check if operation is included
+        const operationMatches = operations.includes(operation);
+        return timingMatches && operationMatches;
+    })
+        .sort((a, b) => {
+        // Sort by priority (lower number = higher priority)
+        const priorityA = DataSemantics[a.id]?.runtime?.priority ?? 100;
+        const priorityB = DataSemantics[b.id]?.runtime?.priority ?? 100;
+        return priorityA - priorityB;
+    });
+}
+/**
+ * Check if a specific semantic can be disabled at runtime
+ */
+export function canSemanticBeDisabled(semanticType) {
+    const definition = DataSemantics[semanticType];
+    return definition?.runtime?.canDisable !== false; // Default to true if not specified
+}
 /**
  * Helper function to get all semantics grouped by category.
  * Useful for organizing semantics in UI dropdowns and forms.