@api-client/core 0.15.1 → 0.16.0

package/src/modeling/definitions/URL.ts

@@ -0,0 +1,96 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration options for the URL semantic.
+ * Controls validation, allowed protocols, and formatting.
+ */
+export interface URLConfig {
+  /**
+   * List of allowed protocols (e.g., ['http', 'https']).
+   */
+  allowedProtocols?: string[]
+  /**
+   * Whether to require HTTPS protocol (default: false).
+   */
+  requireHttps?: boolean
+  /**
+   * Whether to allow query parameters in the URL.
+   */
+  allowQueryParams?: boolean
+  /**
+   * Whether to allow URL fragments (e.g., #section).
+   */
+  allowFragments?: boolean
+  /**
+   * Whether to allow internationalized domain names.
+   */
+  allowInternational?: boolean
+  /**
+   * Whether to allow IP addresses as hostnames.
+   */
+  allowIP?: boolean
+  /**
+   * Whether to allow port numbers in the URL.
+   */
+  allowPort?: boolean
+  /**
+   * Whether to allow authentication info (user:pass@host).
+   */
+  allowAuthentication?: boolean
+  /**
+   * Custom metadata for the URL field.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for URL semantic.
+ */
+export interface AppliedURLSemantic extends AppliedDataSemantic {
+  id: SemanticType.URL
+  config?: URLConfig
+}
+
+/**
+ * Type guard to check if a semantic is a URL semantic.
+ */
+export const isURLSemantic = (semantic: AppliedDataSemantic): semantic is AppliedURLSemantic => {
+  return semantic.id === SemanticType.URL
+}
+
+/**
+ * Helper function to create a URL semantic with configuration.
+ */
+export const createURLSemantic = (config: URLConfig = {}): AppliedURLSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_URL_CONFIG,
+    ...config,
+  }
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.URL,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for URL semantic.
+ */
+export const DEFAULT_URL_CONFIG: URLConfig = {
+  allowedProtocols: ['http', 'https'],
+  requireHttps: false,
+  allowQueryParams: true,
+  allowFragments: true,
+  allowInternational: true,
+  allowIP: true,
+  allowPort: true,
+  allowAuthentication: false,
+}

package/src/modeling/validation/semantic_validation.ts

@@ -1,6 +1,6 @@
 import { DomainEntityKind } from '../../models/kinds.js'
 import type { DataDomain } from '../DataDomain.js'
-import { SemanticType } from '../Semantics.js'
+import { DataSemantics, isPropertySemantic, SemanticType } from '../Semantics.js'
 import type { DomainValidation } from './rules.js'
 
 /**
@@ -29,6 +29,10 @@ export class SemanticValidation {
     const softDeleteSemantics = this.validateSoftDeleteSemantics()
     results.push(...softDeleteSemantics)
 
+    // Validate property semantics data types
+    const propertySemanticsDataTypes = this.validatePropertySemanticsDataTypes()
+    results.push(...propertySemanticsDataTypes)
+
     return results
   }
 
@@ -142,4 +146,34 @@ export class SemanticValidation {
 
     return results
   }
+
+  /**
+   * Validates if property semantics are applied to properties with compatible data types.
+   */
+  private validatePropertySemanticsDataTypes(): DomainValidation[] {
+    const results: DomainValidation[] = []
+
+    for (const entity of this.domain.listEntities()) {
+      for (const property of entity.listProperties()) {
+        for (const appliedSemantic of property.semantics) {
+          const semanticDefinition = DataSemantics[appliedSemantic.id]
+          if (isPropertySemantic(semanticDefinition) && semanticDefinition.applicableDataTypes) {
+            if (!semanticDefinition.applicableDataTypes.includes(property.type)) {
+              results.push({
+                field: 'semantics',
+                rule: 'type_mismatch',
+                message: `The "${property.info.getLabel()}" property has the "${semanticDefinition.displayName}" semantic applied, but its type "${property.type}" is not compatible.`,
+                help: `The "${semanticDefinition.displayName}" semantic can only be applied to properties of type(s): ${semanticDefinition.applicableDataTypes.join(', ')}.`,
+                severity: 'error',
+                key: property.key,
+                kind: property.kind,
+                parent: entity.key,
+              })
+            }
+          }
+        }
+      }
+    }
+    return results
+  }
 }

package/tests/example-test-setup.ts

@@ -0,0 +1,133 @@
+/**
+ * Example test setup and usage guide for API Client Core
+ *
+ * This file demonstrates how to use the testing infrastructure
+ * and provides working examples for both Node.js and browser tests.
+ */
+
+// Node.js test example using Japa
+import { test } from '@japa/runner'
+import { TestUtils } from './test-utils.js'
+
+// Example: Testing a utility function
+test.group('Example Node.js Tests', (group) => {
+  group.each.setup(() => {
+    // Setup before each test
+    // eslint-disable-next-line no-console
+    console.log('Setting up test...')
+  })
+
+  test('should demonstrate basic testing', ({ assert }) => {
+    const result = 'hello world'
+    assert.equal(result, 'hello world')
+    assert.typeOf(result, 'string')
+  })
+
+  test('should test async operations', async ({ assert }) => {
+    const data = TestUtils.generateTestData()
+    assert.typeOf(data.id, 'string')
+    assert.typeOf(data.timestamp, 'number')
+    assert.typeOf(data.randomBoolean, 'boolean')
+  })
+
+  test('should test HTTP mocking', async ({ assert }) => {
+    const mockResponse = TestUtils.createMockResponse(200, { success: true })
+    const cleanup = TestUtils.mockFetch(mockResponse)
+
+    try {
+      const response = await fetch('https://api.example.com/test')
+      const data = await response.json()
+      assert.isTrue(data.success)
+      assert.equal(response.status, 200)
+    } finally {
+      cleanup()
+    }
+  })
+
+  test('should test error handling', async ({ assert }) => {
+    const error = await TestUtils.assertThrows(() => {
+      throw new Error('Test error')
+    }, 'Test error')
+    assert.equal(error.message, 'Test error')
+  })
+
+  test('should validate object properties', ({ assert }) => {
+    const testObj = { name: 'test', value: 42 }
+
+    // This should not throw
+    TestUtils.validateRequiredProperties(testObj, ['name', 'value'])
+
+    // This should throw
+    assert.throws(() => {
+      // @ts-expect-error: Intentionally missing property
+      TestUtils.validateRequiredProperties(testObj, ['name', 'missing'])
+    })
+  })
+
+  test('should create test URLs with parameters', ({ assert }) => {
+    const url = TestUtils.createTestUrl('/api/users', {
+      page: '1',
+      limit: '10',
+    })
+
+    assert.equal(url.pathname, '/api/users')
+    assert.equal(url.searchParams.get('page'), '1')
+    assert.equal(url.searchParams.get('limit'), '10')
+  })
+
+  test('should create test requests', ({ assert }) => {
+    const request = TestUtils.createTestRequest(
+      'POST',
+      'https://api.example.com/users',
+      JSON.stringify({ name: 'John' }),
+      { Authorization: 'Bearer token123' }
+    )
+
+    assert.equal(request.method, 'POST')
+    assert.equal(request.url, 'https://api.example.com/users')
+  })
+
+  test('should create mock auth config', ({ assert }) => {
+    const config = TestUtils.createMockAuthConfig()
+    assert.typeOf(config.clientId, 'string')
+    assert.typeOf(config.clientSecret, 'string')
+    assert.isArray(config.scopes)
+    assert.include(config.scopes, 'read')
+    assert.include(config.scopes, 'write')
+  })
+
+  test('should test with sinon mocks', ({ sinon, assert }) => {
+    const mockObj = {
+      getValue: () => 'original',
+    }
+
+    const stub = sinon.stub(mockObj, 'getValue')
+    stub.returns('mocked')
+
+    assert.equal(mockObj.getValue(), 'mocked')
+
+    stub.restore()
+    assert.equal(mockObj.getValue(), 'original')
+  })
+
+  test('should test timeout behavior', async ({ assert }) => {
+    const start = Date.now()
+    await TestUtils.sleep(100)
+    const elapsed = Date.now() - start
+
+    assert.isAtLeast(elapsed, 90) // Allow some variance
+    assert.isAtMost(elapsed, 150)
+  })
+})
+
+export default {
+  setupNodeTests: () => {
+    // eslint-disable-next-line no-console
+    console.log('Node.js test environment initialized')
+  },
+
+  setupBrowserTests: () => {
+    // eslint-disable-next-line no-console
+    console.log('Browser test environment initialized')
+  },
+}

package/tests/template-node.spec.ts

@@ -0,0 +1,75 @@
+/**
+ * Template for Node.js tests using Japa
+ * Copy this file and rename it to create new test suites.
+ */
+import { test } from '@japa/runner'
+
+test.group('YourModuleName', (group) => {
+  // Setup runs before each test in the group
+  group.each.setup(() => {
+    // Initialize test data, mocks, etc.
+  })
+
+  // Teardown runs after each test in the group
+  group.each.teardown(() => {
+    // Clean up resources, restore mocks, etc.
+  })
+
+  test('should describe what this test does', ({ assert }) => {
+    // Arrange
+    const input = 'test-input'
+
+    // Act
+    const result = input.toUpperCase()
+
+    // Assert
+    assert.equal(result, 'TEST-INPUT')
+  })
+
+  test('should test async operations', async ({ assert }) => {
+    // Arrange
+    const promise = Promise.resolve('async-result')
+
+    // Act
+    const result = await promise
+
+    // Assert
+    assert.equal(result, 'async-result')
+  })
+
+  test('should test error cases', async ({ assert }) => {
+    // Assert that function throws
+    await assert.rejects(() => Promise.reject(new Error('Expected error')), 'Expected error')
+  })
+
+  test('should use sinon for mocking', ({ sinon, assert }) => {
+    // Arrange
+    const mockObject = {
+      method: () => 'original',
+    }
+    const stub = sinon.stub(mockObject, 'method')
+    stub.returns('mocked')
+
+    // Act
+    const result = mockObject.method()
+
+    // Assert
+    assert.equal(result, 'mocked')
+
+    // Cleanup (optional - sinon auto-restores)
+    stub.restore()
+  })
+
+  test('should test with custom timeout', async ({ assert }) => {
+    // This test has a longer timeout
+    const start = Date.now()
+    await new Promise((resolve) => setTimeout(resolve, 100))
+    const elapsed = Date.now() - start
+    assert.isAtLeast(elapsed, 90)
+  }).timeout(5000) // 5 second timeout
+
+  test('should be skipped', ({ assert }) => {
+    // This test is skipped
+    assert.fail('This should not run')
+  }).skip(true)
+})

package/tests/test-utils.ts

@@ -0,0 +1,293 @@
+import { TestContext } from '@japa/runner/core'
+
+/**
+ * Common test utilities for the API Client Core
+ */
+export const TestUtils = {
+  /**
+   * Creates a mock HTTP response
+   */
+  createMockResponse(status = 200, body: unknown = {}, headers: Record<string, string> = {}): Response {
+    return new Response(JSON.stringify(body), {
+      status,
+      headers: {
+        'Content-Type': 'application/json',
+        ...headers,
+      },
+    })
+  },
+
+  /**
+   * Creates a test URL with optional query parameters
+   */
+  createTestUrl(path = '/', params: Record<string, string> = {}): URL {
+    const url = new URL(path, 'https://api.example.com')
+    Object.entries(params).forEach(([key, value]) => {
+      url.searchParams.set(key, value)
+    })
+    return url
+  },
+
+  /**
+   * Waits for a specified amount of time
+   */
+  async sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+  },
+
+  /**
+   * Creates a test request object
+   */
+  createTestRequest(
+    method = 'GET',
+    url: string | URL = 'https://api.example.com',
+    body?: BodyInit,
+    headers: Record<string, string> = {}
+  ): Request {
+    return new Request(url, {
+      method,
+      body,
+      headers: {
+        'Content-Type': 'application/json',
+        ...headers,
+      },
+    })
+  },
+
+  /**
+   * Generates random test data
+   */
+  generateTestData() {
+    return {
+      id: Math.random().toString(36).substr(2, 9),
+      timestamp: Date.now(),
+      randomString: Math.random().toString(36).substr(2, 10),
+      randomNumber: Math.floor(Math.random() * 1000),
+      randomBoolean: Math.random() > 0.5,
+    }
+  },
+
+  /**
+   * Creates a mock authorization configuration
+   */
+  createMockAuthConfig() {
+    return {
+      clientId: 'test-client-id',
+      clientSecret: 'test-client-secret',
+      authorizationUri: 'https://auth.example.com/oauth/authorize',
+      accessTokenUri: 'https://auth.example.com/oauth/token',
+      scopes: ['read', 'write'],
+    }
+  },
+
+  /**
+   * Creates a mock API project structure
+   */
+  createMockProject() {
+    return {
+      kind: 'Project',
+      key: 'test-project',
+      info: {
+        name: 'Test Project',
+        version: '1.0.0',
+        description: 'A test API project',
+      },
+      definitions: {},
+      environments: [],
+      requests: [],
+      folders: [],
+    }
+  },
+
+  /**
+   * Asserts that an error is thrown with specific message
+   */
+  async assertThrows(fn: () => Promise<unknown> | unknown, expectedMessage?: string | RegExp): Promise<Error> {
+    try {
+      await fn()
+      throw new Error('Expected function to throw an error')
+    } catch (error) {
+      const typedError = error as Error
+      if (expectedMessage) {
+        if (typeof expectedMessage === 'string') {
+          if (!typedError.message.includes(expectedMessage)) {
+            throw new Error(`Expected error message to include "${expectedMessage}", got "${typedError.message}"`)
+          }
+        } else if (expectedMessage instanceof RegExp) {
+          if (!expectedMessage.test(typedError.message)) {
+            throw new Error(`Expected error message to match ${expectedMessage}, got "${typedError.message}"`)
+          }
+        }
+      }
+      return typedError
+    }
+  },
+
+  /**
+   * Validates that an object has required properties
+   */
+  validateRequiredProperties<T extends Record<string, unknown>>(obj: T, requiredProps: (keyof T)[]): void {
+    for (const prop of requiredProps) {
+      if (!(prop in obj)) {
+        throw new Error(`Missing required property: ${String(prop)}`)
+      }
+      if (obj[prop] === undefined || obj[prop] === null) {
+        throw new Error(`Property ${String(prop)} cannot be null or undefined`)
+      }
+    }
+  },
+
+  /**
+   * Creates a test environment configuration
+   */
+  createTestEnvironment() {
+    return {
+      variables: [
+        { name: 'baseUrl', value: 'https://api.example.com' },
+        { name: 'apiKey', value: 'test-api-key' },
+        { name: 'version', value: 'v1' },
+      ],
+      oauth2: {
+        port: 8080,
+        issuer: 'https://oauth.example.com',
+      },
+    }
+  },
+
+  /**
+   * Mocks the fetch function with a custom response
+   */
+  mockFetch(response: Response | ((input: RequestInfo | URL, init?: RequestInit) => Response)): () => void {
+    const originalFetch = globalThis.fetch
+
+    globalThis.fetch =
+      typeof response === 'function'
+        ? (input: RequestInfo | URL, init?: RequestInit) =>
+            Promise.resolve((response as (input: RequestInfo | URL, init?: RequestInit) => Response)(input, init))
+        : () => Promise.resolve(response)
+
+    // Return cleanup function
+    return () => {
+      globalThis.fetch = originalFetch
+    }
+  },
+}
+
+/**
+ * Test decorators and helpers for Japa tests
+ */
+export const JapaTestHelpers = {
+  /**
+   * Timeout decorator for tests that may take longer
+   */
+  timeout(ms: number) {
+    return function (target: unknown, propertyKey: string, descriptor: PropertyDescriptor) {
+      const originalMethod = descriptor.value
+      descriptor.value = function (...args: unknown[]) {
+        const [context] = args
+        // Set timeout on test context (implementation may vary)
+        if (context && typeof context === 'object' && 'timeout' in context) {
+          ;(context as { timeout: number }).timeout = ms
+        }
+        return originalMethod.apply(this, args)
+      }
+    }
+  },
+
+  /**
+   * Skip test conditionally
+   */
+  skipIf(condition: boolean, reason?: string) {
+    return function (target: unknown, propertyKey: string, descriptor: PropertyDescriptor) {
+      if (condition) {
+        descriptor.value = function (context: TestContext) {
+          context.test.skip(true, reason || 'Skipped conditionally')
+        }
+      }
+    }
+  },
+
+  /**
+   * Run test only in specific environment
+   */
+  onlyInEnvironment(env: 'node' | 'browser') {
+    return function (target: unknown, propertyKey: string, descriptor: PropertyDescriptor) {
+      // eslint-disable-next-line no-restricted-globals
+      const isNode = typeof window === 'undefined'
+      const shouldRun = (env === 'node' && isNode) || (env === 'browser' && !isNode)
+
+      if (!shouldRun) {
+        descriptor.value = function (context: TestContext) {
+          context.test.skip(true, `Only runs in ${env} environment`)
+        }
+      }
+    }
+  },
+}
+
+/**
+ * Browser-specific test utilities
+ */
+export const BrowserTestUtils = {
+  /**
+   * Simulates a browser event
+   */
+  dispatchEvent(element: Element, eventType: string, options: EventInit = {}): Event {
+    const event = new Event(eventType, { bubbles: true, cancelable: true, ...options })
+    element.dispatchEvent(event)
+    return event
+  },
+
+  /**
+   * Creates a mock localStorage implementation
+   */
+  createMockLocalStorage(): Storage {
+    const storage: Record<string, string> = {}
+
+    return {
+      getItem: (key: string) => storage[key] || null,
+      setItem: (key: string, value: string) => {
+        storage[key] = value
+      },
+      removeItem: (key: string) => {
+        // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+        delete storage[key]
+      },
+      clear: () => {
+        Object.keys(storage).forEach((key) => {
+          // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+          delete storage[key]
+        })
+      },
+      key: (index: number) => Object.keys(storage)[index] || null,
+      get length() {
+        return Object.keys(storage).length
+      },
+    }
+  },
+
+  /**
+   * Waits for DOM element to appear
+   */
+  async waitForElement(selector: string, timeout = 5000): Promise<Element> {
+    const startTime = Date.now()
+
+    while (Date.now() - startTime < timeout) {
+      // eslint-disable-next-line no-restricted-globals
+      const element = document.querySelector(selector)
+      if (element) {
+        return element
+      }
+      await TestUtils.sleep(50)
+    }
+
+    throw new Error(`Element with selector "${selector}" not found within ${timeout}ms`)
+  },
+
+  /**
+   * Creates a mock file for file upload testing
+   */
+  createMockFile(name = 'test.txt', content = 'test content', type = 'text/plain'): File {
+    return new File([content], name, { type })
+  },
+}

package/tests/unit/modeling/definitions/calculated.spec.ts

@@ -0,0 +1,33 @@
+import { test } from '@japa/runner'
+import {
+  createCalculatedSemantic,
+  isCalculatedSemantic,
+  type CalculatedConfig,
+} from '../../../../src/modeling/definitions/Calculated.js'
+import { SemanticType, type AppliedDataSemantic } from '../../../../src/modeling/Semantics.js'
+
+test.group('Calculated Semantic Configuration', () => {
+  test('should create semantic with custom config', ({ assert }) => {
+    const config: CalculatedConfig = {
+      formula: 'price * quantity',
+      dependencies: ['price', 'quantity'],
+      recalculateOnUpdate: true,
+      allowManualOverride: true,
+    }
+    const semantic = createCalculatedSemantic(config)
+    assert.equal(semantic.id, SemanticType.Calculated)
+    assert.deepEqual(semantic.config, config)
+  })
+
+  test('should identify calculated semantic', ({ assert }) => {
+    const config: CalculatedConfig = { formula: 'price * quantity' }
+    const semantic = createCalculatedSemantic(config)
+    assert.isTrue(isCalculatedSemantic(semantic))
+  })
+
+  test('should not identify non-calculated semantic', ({ assert }) => {
+    // Simulate a different semantic
+    const fakeSemantic: AppliedDataSemantic = { id: SemanticType.Email, config: {} }
+    assert.isFalse(isCalculatedSemantic(fakeSemantic))
+  })
+})