@api-client/core 0.15.1 → 0.16.1

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

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

@@ -0,0 +1,38 @@
+import { test } from '@japa/runner'
+import {
+  createCategoriesSemantic,
+  isCategoriesSemantic,
+  DEFAULT_CATEGORIES_CONFIG,
+  type CategoriesConfig,
+} from '../../../../src/modeling/definitions/Categories.js'
+import { SemanticType, type AppliedDataSemantic } from '../../../../src/modeling/Semantics.js'
+
+test.group('Categories Semantic Configuration', () => {
+  test('should create semantic with default config', ({ assert }) => {
+    const semantic = createCategoriesSemantic()
+    assert.equal(semantic.id, SemanticType.Categories)
+    assert.deepEqual(semantic.config, DEFAULT_CATEGORIES_CONFIG)
+  })
+
+  test('should create semantic with custom config', ({ assert }) => {
+    const config: CategoriesConfig = {
+      maxCategories: 5,
+      allowMultiple: true,
+      predefinedCategories: ['feature', 'bug', 'enhancement'],
+    }
+    const semantic = createCategoriesSemantic(config)
+    assert.equal(semantic.id, SemanticType.Categories)
+    assert.deepEqual(semantic.config, { ...DEFAULT_CATEGORIES_CONFIG, ...config })
+  })
+
+  test('should identify categories semantic', ({ assert }) => {
+    const semantic = createCategoriesSemantic()
+    assert.isTrue(isCategoriesSemantic(semantic))
+  })
+
+  test('should not identify non-categories semantic', ({ assert }) => {
+    // Simulate a different semantic
+    const fakeSemantic: AppliedDataSemantic = { id: SemanticType.Email, config: {} }
+    assert.isFalse(isCategoriesSemantic(fakeSemantic))
+  })
+})

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

@@ -0,0 +1,34 @@
+import { test } from '@japa/runner'
+import {
+  createDerivedSemantic,
+  isDerivedSemantic,
+  type DerivedConfig,
+} from '../../../../src/modeling/definitions/Derived.js'
+import { SemanticType, type AppliedDataSemantic } from '../../../../src/modeling/Semantics.js'
+
+test.group('Derived Semantic Configuration', () => {
+  test('should create semantic with custom config', ({ assert }) => {
+    const config: DerivedConfig = {
+      sourceFields: ['firstName', 'lastName'],
+      derivationRule: 'concat',
+      updateOnChange: true,
+      allowManualOverride: true,
+      recalculateOnUpdate: false,
+    }
+    const semantic = createDerivedSemantic(config)
+    assert.equal(semantic.id, SemanticType.Derived)
+    assert.deepEqual(semantic.config, config)
+  })
+
+  test('should identify derived semantic', ({ assert }) => {
+    const config: DerivedConfig = { sourceFields: ['firstName', 'lastName'] }
+    const semantic = createDerivedSemantic(config)
+    assert.isTrue(isDerivedSemantic(semantic))
+  })
+
+  test('should not identify non-derived semantic', ({ assert }) => {
+    // Simulate a different semantic
+    const fakeSemantic: AppliedDataSemantic = { id: SemanticType.Email, config: {} }
+    assert.isFalse(isDerivedSemantic(fakeSemantic))
+  })
+})

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

@@ -0,0 +1,38 @@
+import { test } from '@japa/runner'
+import {
+  createDescriptionSemantic,
+  isDescriptionSemantic,
+  DEFAULT_DESCRIPTION_CONFIG,
+  type DescriptionConfig,
+} from '../../../../src/modeling/definitions/Description.js'
+import { SemanticType, type AppliedDataSemantic } from '../../../../src/modeling/Semantics.js'
+
+test.group('Description Semantic Configuration', () => {
+  test('should create semantic with default config', ({ assert }) => {
+    const semantic = createDescriptionSemantic()
+    assert.equal(semantic.id, SemanticType.Description)
+    assert.deepEqual(semantic.config, DEFAULT_DESCRIPTION_CONFIG)
+  })
+
+  test('should create semantic with custom config', ({ assert }) => {
+    const config: DescriptionConfig = {
+      minLength: 10,
+      maxLength: 1000,
+      allowMarkdown: true,
+    }
+    const semantic = createDescriptionSemantic(config)
+    assert.equal(semantic.id, SemanticType.Description)
+    assert.deepEqual(semantic.config, { ...DEFAULT_DESCRIPTION_CONFIG, ...config })
+  })
+
+  test('should identify description semantic', ({ assert }) => {
+    const semantic = createDescriptionSemantic()
+    assert.isTrue(isDescriptionSemantic(semantic))
+  })
+
+  test('should not identify non-description semantic', ({ assert }) => {
+    // Simulate a different semantic
+    const fakeSemantic: AppliedDataSemantic = { id: SemanticType.Email, config: {} }
+    assert.isFalse(isDescriptionSemantic(fakeSemantic))
+  })
+})

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

@@ -0,0 +1,38 @@
+import { test } from '@japa/runner'
+import {
+  createEmailSemantic,
+  isEmailSemantic,
+  DEFAULT_EMAIL_CONFIG,
+  type EmailConfig,
+} from '../../../../src/modeling/definitions/Email.js'
+import { SemanticType, type AppliedDataSemantic } from '../../../../src/modeling/Semantics.js'
+
+test.group('Email Semantic Configuration', () => {
+  test('should create semantic with default config', ({ assert }) => {
+    const semantic = createEmailSemantic()
+    assert.equal(semantic.id, SemanticType.Email)
+    assert.deepEqual(semantic.config, DEFAULT_EMAIL_CONFIG)
+  })
+
+  test('should create semantic with custom config', ({ assert }) => {
+    const config: EmailConfig = {
+      allowedDomains: ['example.com'],
+      requireVerification: true,
+      verificationMethod: 'email',
+    }
+    const semantic = createEmailSemantic(config)
+    assert.equal(semantic.id, SemanticType.Email)
+    assert.deepEqual(semantic.config, { ...DEFAULT_EMAIL_CONFIG, ...config })
+  })
+
+  test('should identify email semantic', ({ assert }) => {
+    const semantic = createEmailSemantic()
+    assert.isTrue(isEmailSemantic(semantic))
+  })
+
+  test('should not identify non-email semantic', ({ assert }) => {
+    // Simulate a different semantic
+    const fakeSemantic: AppliedDataSemantic = { id: SemanticType.Phone, config: {} }
+    assert.isFalse(isEmailSemantic(fakeSemantic))
+  })
+})

package/tests/unit/modeling/definitions/geospatial-coordinates.spec.ts

@@ -0,0 +1,41 @@
+import { test } from '@japa/runner'
+import {
+  createGeospatialCoordinatesSemantic,
+  isGeospatialCoordinatesSemantic,
+  DEFAULT_GEOSPATIAL_CONFIG,
+  type GeospatialCoordinatesConfig,
+  GeospatialCoordinateFormat,
+  GeospatialDistanceUnit,
+  GeospatialSpatialReferenceSystem,
+} from '../../../../src/modeling/definitions/GeospatialCoordinates.js'
+import { SemanticType, type AppliedDataSemantic } from '../../../../src/modeling/Semantics.js'
+
+test.group('GeospatialCoordinates Semantic Configuration', () => {
+  test('should create semantic with default config', ({ assert }) => {
+    const semantic = createGeospatialCoordinatesSemantic()
+    assert.equal(semantic.id, SemanticType.GeospatialCoordinates)
+    assert.deepEqual(semantic.config, DEFAULT_GEOSPATIAL_CONFIG)
+  })
+
+  test('should create semantic with custom config', ({ assert }) => {
+    const config: GeospatialCoordinatesConfig = {
+      format: GeospatialCoordinateFormat.LatLon,
+      defaultDistanceUnit: GeospatialDistanceUnit.Kilometers,
+      spatialReferenceSystem: GeospatialSpatialReferenceSystem.WGS84,
+    }
+    const semantic = createGeospatialCoordinatesSemantic(config)
+    assert.equal(semantic.id, SemanticType.GeospatialCoordinates)
+    assert.deepEqual(semantic.config, { ...DEFAULT_GEOSPATIAL_CONFIG, ...config })
+  })
+
+  test('should identify geospatial semantic', ({ assert }) => {
+    const semantic = createGeospatialCoordinatesSemantic()
+    assert.isTrue(isGeospatialCoordinatesSemantic(semantic))
+  })
+
+  test('should not identify non-geospatial semantic', ({ assert }) => {
+    // Simulate a different semantic
+    const fakeSemantic: AppliedDataSemantic = { id: SemanticType.Email, config: {} }
+    assert.isFalse(isGeospatialCoordinatesSemantic(fakeSemantic))
+  })
+})

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

@@ -0,0 +1,38 @@
+import { test } from '@japa/runner'
+import {
+  createHTMLSemantic,
+  isHTMLSemantic,
+  DEFAULT_HTML_CONFIG,
+  type HTMLConfig,
+} from '../../../../src/modeling/definitions/HTML.js'
+import { SemanticType, type AppliedDataSemantic } from '../../../../src/modeling/Semantics.js'
+
+test.group('HTML Semantic Configuration', () => {
+  test('should create semantic with default config', ({ assert }) => {
+    const semantic = createHTMLSemantic()
+    assert.equal(semantic.id, SemanticType.HTML)
+    assert.deepEqual(semantic.config, DEFAULT_HTML_CONFIG)
+  })
+
+  test('should create semantic with custom config', ({ assert }) => {
+    const config: HTMLConfig = {
+      renderAsHTML: true,
+      allowedTags: ['p', 'div', 'span'],
+      sanitize: true,
+    }
+    const semantic = createHTMLSemantic(config)
+    assert.equal(semantic.id, SemanticType.HTML)
+    assert.deepEqual(semantic.config, { ...DEFAULT_HTML_CONFIG, ...config })
+  })
+
+  test('should identify HTML semantic', ({ assert }) => {
+    const semantic = createHTMLSemantic()
+    assert.isTrue(isHTMLSemantic(semantic))
+  })
+
+  test('should not identify non-HTML semantic', ({ assert }) => {
+    // Simulate a different semantic
+    const fakeSemantic: AppliedDataSemantic = { id: SemanticType.Markdown, config: {} }
+    assert.isFalse(isHTMLSemantic(fakeSemantic))
+  })
+})

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

@@ -0,0 +1,38 @@
+import { test } from '@japa/runner'
+import {
+  createMarkdownSemantic,
+  isMarkdownSemantic,
+  DEFAULT_MARKDOWN_CONFIG,
+  type MarkdownConfig,
+} from '../../../../src/modeling/definitions/Markdown.js'
+import { SemanticType, type AppliedDataSemantic } from '../../../../src/modeling/Semantics.js'
+
+test.group('Markdown Semantic Configuration', () => {
+  test('should create semantic with default config', ({ assert }) => {
+    const semantic = createMarkdownSemantic()
+    assert.equal(semantic.id, SemanticType.Markdown)
+    assert.deepEqual(semantic.config, DEFAULT_MARKDOWN_CONFIG)
+  })
+
+  test('should create semantic with custom config', ({ assert }) => {
+    const config: MarkdownConfig = {
+      renderToHTML: true,
+      allowedTags: ['p', 'h1', 'h2'],
+      sanitize: true,
+    }
+    const semantic = createMarkdownSemantic(config)
+    assert.equal(semantic.id, SemanticType.Markdown)
+    assert.deepEqual(semantic.config, { ...DEFAULT_MARKDOWN_CONFIG, ...config })
+  })
+
+  test('should identify markdown semantic', ({ assert }) => {
+    const semantic = createMarkdownSemantic()
+    assert.isTrue(isMarkdownSemantic(semantic))
+  })
+
+  test('should not identify non-markdown semantic', ({ assert }) => {
+    // Simulate a different semantic
+    const fakeSemantic: AppliedDataSemantic = { id: SemanticType.Email, config: {} }
+    assert.isFalse(isMarkdownSemantic(fakeSemantic))
+  })
+})