@api-client/core 0.15.1 → 0.16.1

package/src/modeling/definitions/Summary.ts

@@ -0,0 +1,73 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration for the Summary semantic.
+ * Summary is a simple semantic without configuration options.
+ */
+export interface SummaryConfig {
+  /**
+   * Custom metadata for the summary field.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Default configuration for the Summary semantic.
+ */
+export const DEFAULT_SUMMARY_CONFIG: SummaryConfig = {}
+
+/**
+ * Creates a Summary semantic application.
+ * @param config - Optional configuration (not used for simple semantic)
+ * @returns AppliedDataSemantic for Summary
+ */
+export const createSummarySemantic = (config?: SummaryConfig): AppliedDataSemantic => ({
+  id: SemanticType.Summary,
+  config: config ? { ...DEFAULT_SUMMARY_CONFIG, ...config } : { ...DEFAULT_SUMMARY_CONFIG },
+})
+
+/**
+ * Type guard to check if a semantic is a Summary semantic.
+ * @param semantic - The semantic to check
+ * @returns True if the semantic is a Summary semantic
+ */
+export const isSummarySemantic = (
+  semantic: AppliedDataSemantic
+): semantic is AppliedDataSemantic & { id: SemanticType.Summary } => semantic.id === SemanticType.Summary
+
+/**
+ * Extracts the configuration from a Summary semantic application.
+ * @param semantic - The semantic application
+ * @returns The Summary configuration or undefined if not a Summary semantic
+ */
+export const getSummaryConfig = (semantic: AppliedDataSemantic): SummaryConfig | undefined => {
+  if (!isSummarySemantic(semantic)) {
+    return undefined
+  }
+  return semantic.config as SummaryConfig | undefined
+}
+
+/**
+ * Validates Summary semantic configuration.
+ * @returns True if the configuration is valid
+ */
+export const validateSummaryConfig = (): boolean => {
+  // No validation needed for simple semantic
+  return true
+}
+
+/**
+ * Merges Summary configurations, with the second config taking precedence.
+ * @param base - The base configuration
+ * @param override - The configuration to merge on top
+ * @returns Merged configuration
+ */
+export const mergeSummaryConfig = (base: SummaryConfig, override: SummaryConfig): SummaryConfig => {
+  // No merging needed for simple semantic
+  return { ...base, ...override }
+}

package/src/modeling/definitions/Tags.ts

@@ -0,0 +1,75 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration options for the Tags semantic.
+ * Controls allowed tags, validation, and formatting for associations.
+ */
+export interface TagsConfig {
+  /**
+   * List of allowed tags.
+   */
+  allowedTags?: string[]
+  /**
+   * Whether to allow custom tags not in the allowedTags list.
+   */
+  allowCustomTags?: boolean
+  /**
+   * Whether tags are case sensitive.
+   */
+  caseSensitive?: boolean
+  /**
+   * Whether to allow Unicode characters in tags.
+   */
+  allowUnicode?: boolean
+  /**
+   * Custom metadata for the tags association.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for Tags semantic.
+ */
+export interface AppliedTagsSemantic extends AppliedDataSemantic {
+  id: SemanticType.Tags
+  config?: TagsConfig
+}
+
+/**
+ * Type guard to check if a semantic is a Tags semantic.
+ */
+export const isTagsSemantic = (semantic: AppliedDataSemantic): semantic is AppliedTagsSemantic => {
+  return semantic.id === SemanticType.Tags
+}
+
+/**
+ * Helper function to create a Tags semantic with configuration.
+ */
+export const createTagsSemantic = (config: TagsConfig = {}): AppliedTagsSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_TAGS_CONFIG,
+    ...config,
+  }
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.Tags,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for Tags semantic.
+ */
+export const DEFAULT_TAGS_CONFIG: TagsConfig = {
+  allowCustomTags: true,
+  caseSensitive: false,
+  allowUnicode: false,
+}

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)
+})