@api-client/core 0.20.2 → 0.20.4

package/src/runtime/modeling/Semantics.ts

@@ -1,196 +0,0 @@
-import { Jexl } from '@pawel-up/jexl/Jexl.js'
-import type { DomainEntity } from '../../modeling/DomainEntity.js'
-import {
-  type AppliedDataSemantic,
-  DataSemantics,
-  type SemanticCondition,
-  SemanticOperation,
-  SemanticType,
-} from '../../modeling/Semantics.js'
-import type { TransformFunction } from '@pawel-up/jexl'
-
-/**
- * Cache for JEXL instances to avoid recreation overhead
- */
-const jexlCache = new Map<string, Jexl>()
-
-/**
- * Get or create a JEXL instance with optional custom transforms
- */
-export function getJexlInstance(transforms?: Record<string, TransformFunction>): Jexl {
-  const cacheKey = transforms ? JSON.stringify(Object.keys(transforms).sort()) : 'default'
-
-  if (!jexlCache.has(cacheKey)) {
-    const jexl = new Jexl()
-    if (transforms) {
-      Object.entries(transforms).forEach(([name, fn]) => {
-        jexl.addTransform(name, fn)
-      })
-    }
-    jexlCache.set(cacheKey, jexl)
-  }
-
-  return jexlCache.get(cacheKey) as Jexl
-}
-
-/**
- * Context object passed to semantic condition evaluation
- */
-export interface SemanticExecutionContext {
-  /**
-   * The entity data being processed
-   */
-  entity: Record<string, unknown>
-  /**
-   * Current user context (if authenticated)
-   */
-  user?: {
-    id?: string
-    authenticated?: boolean
-    roles?: string[]
-    [key: string]: unknown
-  }
-  /**
-   * The current database operation
-   */
-  operation: SemanticOperation
-  /**
-   * Applied semantics with their field mappings
-   */
-  appliedSemantics: AppliedDataSemantic[]
-  /**
-   * Configuration for the current semantic being evaluated
-   */
-  config?: Record<string, unknown>
-}
-
-/**
- * Builds a semantics object for JEXL evaluation that maps semantic types to actual field names.
- *
- * The resulting map should be used in JEXL expressions to reference semantic fields.
- *
- * @returns A map where keys are semantic type identifiers and values are the field names.
- *
- * @example
- * const semanticFieldMap = buildSemanticFieldMap(entity);
- * const result = await jexl.eval("semantics.CreatedTimestamp == null", {
- *  semantics: semanticFieldMap,
- *  ...
- * }
- */
-export function buildSemanticFieldMap(entity: DomainEntity): Record<string, string> {
-  const semanticFieldMap: Record<string, string> = {}
-
-  for (const property of entity.properties) {
-    if (!property.info.name) {
-      continue // Skip properties without a name
-    }
-    for (const semantic of property.semantics) {
-      // We use the truncated `semantic.id` as the key, e.g. 'Password' so that it is possible to do something like:
-      // `entity[semantics.Password] != null && !entity[semantics.Password].startsWith('$')`
-      // Where the `semantics` object is the object returned by this function and
-      // passed to the JEXL context.
-      const semanticKey = semantic.id.replace('Semantic#', '')
-      semanticFieldMap[semanticKey] = property.info.name
-    }
-  }
-  return semanticFieldMap
-}
-
-/**
- * Evaluates a semantic condition against the execution context
- * In a real implementation, this would use JEXL to evaluate the expression
- *
- * @param condition The semantic condition to evaluate
- * @param context The execution context containing entity data, user info, etc.
- * @param semanticFieldMap A map of semantic field names to their actual field names.
- *                         Use the `buildSemanticFieldMap()` function to create this map.
- * @param jexl Optional JEXL instance to use for evaluation, defaults to a cached instance.
- * @returns A promise that resolves to true if the condition is met, false otherwise
- */
-export function evaluateSemanticCondition(
-  condition: SemanticCondition,
-  context: SemanticExecutionContext,
-  semanticFieldMap: Record<string, string>,
-  jexl: Jexl = getJexlInstance()
-): Promise<boolean> {
-  // Build the evaluation context
-  const evalContext = {
-    entity: context.entity,
-    user: context.user,
-    operation: context.operation,
-    config: context.config,
-    semantics: semanticFieldMap,
-  }
-  return jexl.eval(condition.expression, evalContext)
-}
-
-/**
- * Check if semantic should execute based on all its conditions
- *
- * @param semantic The semantic to check
- * @param context The execution context containing entity data, user info, etc.
- * @param semanticFieldMap A map of semantic field names to their actual field names.
- *                         Use the `buildSemanticFieldMap()` function to create this map.
- * @return A promise that resolves to true if all conditions are met, false otherwise
- */
-export async function shouldSemanticExecute(
-  semantic: AppliedDataSemantic,
-  context: SemanticExecutionContext,
-  semanticFieldMap: Record<string, string>
-): Promise<boolean> {
-  const definition = DataSemantics[semantic.id]
-  const conditions = definition?.runtime?.conditions
-
-  if (!conditions || conditions.length === 0) {
-    return true
-  }
-
-  const results = await Promise.all(
-    conditions.map((condition) => evaluateSemanticCondition(condition, context, semanticFieldMap))
-  )
-  // All conditions must evaluate to true
-  return results.every((result) => result === true)
-}
-
-/**
- * Helper to get the actual field name for a semantic type
- */
-export function getFieldNameForSemantic(
-  semanticType: SemanticType,
-  semanticFieldMap: Record<string, string>
-): string | undefined {
-  const semanticKey = semanticType.replace('Semantic#', '')
-  return semanticFieldMap[semanticKey]
-}
-
-/**
- * Validates that all semantic references in conditions are available
- */
-export function validateSemanticConditions(
-  semantic: AppliedDataSemantic,
-  semanticFieldMap: Record<string, string>
-): string[] {
-  const definition = DataSemantics[semantic.id]
-  const conditions = definition?.runtime?.conditions || []
-  const errors: string[] = []
-
-  conditions.forEach((condition, index) => {
-    // Extract semantic references from the condition expression
-    // Look for patterns like "semantics.CreatedTimestamp" or "entity[semantics.Password]"
-    const semanticMatches = condition.expression.match(/semantics\.(\w+)/g)
-
-    if (semanticMatches) {
-      semanticMatches.forEach((match) => {
-        const semanticKey = match.replace('semantics.', '')
-        if (!semanticFieldMap[semanticKey]) {
-          errors.push(
-            `Condition ${index + 1} references semantic "${semanticKey}" but no field with that semantic was found`
-          )
-        }
-      })
-    }
-  })
-
-  return errors
-}

package/tests/unit/modeling/semantic_runtime.spec.ts

@@ -1,113 +0,0 @@
-import { test } from '@japa/runner'
-import {
-  SemanticType,
-  SemanticTiming,
-  SemanticOperation,
-  getSemanticsForOperation,
-  canSemanticBeDisabled,
-  type AppliedDataSemantic,
-} from '../../../src/modeling/Semantics.js'
-
-test.group('Semantic Runtime Control', () => {
-  test('getSemanticsForOperation should filter semantics by operation and timing', ({ assert }) => {
-    const semantics: AppliedDataSemantic[] = [
-      { id: SemanticType.Password },
-      { id: SemanticType.CreatedTimestamp },
-      { id: SemanticType.UpdatedTimestamp },
-      { id: SemanticType.Status },
-      { id: SemanticType.Title },
-    ]
-
-    // Test CREATE operation with BEFORE timing
-    const createBeforeSemantics = getSemanticsForOperation(semantics, SemanticOperation.Create, SemanticTiming.Before)
-    const createBeforeTypes = createBeforeSemantics.map((s) => s.id)
-
-    assert.includeMembers(createBeforeTypes, [SemanticType.Password, SemanticType.CreatedTimestamp])
-    assert.notInclude(createBeforeTypes, SemanticType.UpdatedTimestamp) // Only runs on UPDATE
-    assert.notInclude(createBeforeTypes, SemanticType.Title) // No runtime operations
-
-    // Test UPDATE operation with BEFORE timing
-    const updateBeforeSemantics = getSemanticsForOperation(semantics, SemanticOperation.Update, SemanticTiming.Before)
-    const updateBeforeTypes = updateBeforeSemantics.map((s) => s.id)
-
-    assert.includeMembers(updateBeforeTypes, [SemanticType.Password, SemanticType.UpdatedTimestamp])
-    assert.notInclude(updateBeforeTypes, SemanticType.CreatedTimestamp) // Only runs on CREATE
-
-    // Test Status semantic runs on both CREATE and UPDATE
-    assert.include(createBeforeTypes, SemanticType.Status)
-    assert.include(updateBeforeTypes, SemanticType.Status)
-  })
-
-  test('getSemanticsForOperation should sort semantics by priority', ({ assert }) => {
-    const semantics: AppliedDataSemantic[] = [
-      { id: SemanticType.Password }, // priority: 10
-      { id: SemanticType.ResourceOwnerIdentifier }, // priority: 5
-      { id: SemanticType.UserRole }, // priority: 20
-    ]
-
-    const createSemantics = getSemanticsForOperation(semantics, SemanticOperation.Create, SemanticTiming.Before)
-
-    // Should be sorted by priority: ResourceOwnerIdentifier (5), Password (10), UserRole (20)
-    assert.equal(createSemantics[0].id, SemanticType.ResourceOwnerIdentifier)
-    assert.equal(createSemantics[1].id, SemanticType.Password)
-    assert.equal(createSemantics[2].id, SemanticType.UserRole)
-  })
-
-  test('getSemanticsForOperation should handle BOTH timing correctly', ({ assert }) => {
-    const semantics: AppliedDataSemantic[] = [
-      { id: SemanticType.Status }, // timing: Both
-      { id: SemanticType.Password }, // timing: Before
-    ]
-
-    const beforeSemantics = getSemanticsForOperation(semantics, SemanticOperation.Create, SemanticTiming.Before)
-    const afterSemantics = getSemanticsForOperation(semantics, SemanticOperation.Create, SemanticTiming.After)
-
-    // Status should appear in both BEFORE and AFTER
-    assert.equal(beforeSemantics.length, 2) // Status and Password
-    assert.equal(afterSemantics.length, 1) // Only Status
-    assert.equal(afterSemantics[0].id, SemanticType.Status)
-  })
-
-  test('canSemanticBeDisabled should check if semantic can be disabled', ({ assert }) => {
-    // Security semantics cannot be disabled
-    assert.isFalse(canSemanticBeDisabled(SemanticType.Password))
-    assert.isFalse(canSemanticBeDisabled(SemanticType.ResourceOwnerIdentifier))
-
-    // Other semantics can be disabled (default)
-    assert.isTrue(canSemanticBeDisabled(SemanticType.CreatedTimestamp))
-    assert.isTrue(canSemanticBeDisabled(SemanticType.Email))
-    assert.isTrue(canSemanticBeDisabled(SemanticType.Status))
-  })
-
-  test('getSemanticsForOperation should return empty array for semantics with no runtime', ({ assert }) => {
-    const semantics: AppliedDataSemantic[] = [
-      { id: SemanticType.Title }, // No runtime operations
-      { id: SemanticType.Description }, // No runtime operations
-      { id: SemanticType.User }, // No runtime operations
-    ]
-
-    const result = getSemanticsForOperation(semantics, SemanticOperation.Create, SemanticTiming.Before)
-    assert.lengthOf(result, 0)
-  })
-
-  test('getSemanticsForOperation should filter by specific operations', ({ assert }) => {
-    const semantics: AppliedDataSemantic[] = [
-      { id: SemanticType.CreatedTimestamp }, // Only CREATE
-      { id: SemanticType.UpdatedTimestamp }, // Only UPDATE
-      { id: SemanticType.DeletedTimestamp }, // Only DELETE
-    ]
-
-    const createSemantics = getSemanticsForOperation(semantics, SemanticOperation.Create, SemanticTiming.Before)
-    const updateSemantics = getSemanticsForOperation(semantics, SemanticOperation.Update, SemanticTiming.Before)
-    const deleteSemantics = getSemanticsForOperation(semantics, SemanticOperation.Delete, SemanticTiming.Before)
-
-    assert.lengthOf(createSemantics, 1)
-    assert.equal(createSemantics[0].id, SemanticType.CreatedTimestamp)
-
-    assert.lengthOf(updateSemantics, 1)
-    assert.equal(updateSemantics[0].id, SemanticType.UpdatedTimestamp)
-
-    assert.lengthOf(deleteSemantics, 1)
-    assert.equal(deleteSemantics[0].id, SemanticType.DeletedTimestamp)
-  })
-})