@api-client/core 0.15.1 → 0.16.0

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

@@ -0,0 +1,465 @@
+import { test } from '@japa/runner'
+import {
+  createPriceSemantic,
+  isPriceSemantic,
+  validatePriceConfig,
+  DEFAULT_PRICE_CONFIG,
+  PRICE_PRESETS,
+  type PriceConfig,
+} from '../../../../src/modeling/definitions/Price.js'
+import { SemanticType, type AppliedDataSemantic } from '../../../../src/modeling/Semantics.js'
+
+test.group('Price Semantic Configuration', () => {
+  test('should create semantic with default config', ({ assert }) => {
+    const semantic = createPriceSemantic()
+    assert.equal(semantic.id, SemanticType.Price)
+    assert.deepEqual(semantic.config, DEFAULT_PRICE_CONFIG)
+  })
+
+  test('should create semantic with custom config', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'complex_object',
+      allowedCurrencies: ['USD', 'EUR'],
+      decimalPlaces: 4,
+      allowNegative: true,
+      validateCurrencyCode: false,
+    }
+    const semantic = createPriceSemantic(config)
+    assert.equal(semantic.id, SemanticType.Price)
+    assert.deepEqual(semantic.config, { ...DEFAULT_PRICE_CONFIG, ...config })
+  })
+
+  test('should merge metadata properly', ({ assert }) => {
+    const config: PriceConfig = {
+      metadata: {
+        customField: 'value',
+        anotherField: 123,
+      },
+    }
+    const semantic = createPriceSemantic(config)
+    assert.equal(semantic.id, SemanticType.Price)
+    assert.deepEqual(semantic.config?.metadata, config.metadata)
+  })
+
+  test('should identify price semantic', ({ assert }) => {
+    const semantic = createPriceSemantic()
+    assert.isTrue(isPriceSemantic(semantic))
+  })
+
+  test('should not identify non-price semantic', ({ assert }) => {
+    const fakeSemantic: AppliedDataSemantic = {
+      id: SemanticType.Email,
+      config: {},
+    }
+    assert.isFalse(isPriceSemantic(fakeSemantic))
+  })
+
+  test('DEFAULT_PRICE_CONFIG should have correct values', ({ assert }) => {
+    assert.equal(DEFAULT_PRICE_CONFIG.storageFormat, 'decimal')
+    assert.equal(DEFAULT_PRICE_CONFIG.defaultCurrency, 'USD')
+    assert.equal(DEFAULT_PRICE_CONFIG.decimalPlaces, 2)
+    assert.equal(DEFAULT_PRICE_CONFIG.allowNegative, false)
+    assert.equal(DEFAULT_PRICE_CONFIG.validateCurrencyCode, true)
+  })
+})
+
+test.group('Price Storage Formats', () => {
+  test('should support decimal storage format', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'decimal',
+      defaultCurrency: 'USD',
+      decimalPlaces: 2,
+    }
+    const semantic = createPriceSemantic(config)
+    assert.equal(semantic.config?.storageFormat, 'decimal')
+    assert.equal(semantic.config?.defaultCurrency, 'USD')
+    assert.equal(semantic.config?.decimalPlaces, 2)
+  })
+
+  test('should support integer_cents storage format', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'integer_cents',
+      defaultCurrency: 'EUR',
+      decimalPlaces: 2,
+    }
+    const semantic = createPriceSemantic(config)
+    assert.equal(semantic.config?.storageFormat, 'integer_cents')
+    assert.equal(semantic.config?.defaultCurrency, 'EUR')
+  })
+
+  test('should support complex_object storage format', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'complex_object',
+      allowedCurrencies: ['USD', 'EUR', 'GBP'],
+      decimalPlaces: 2,
+    }
+    const semantic = createPriceSemantic(config)
+    assert.equal(semantic.config?.storageFormat, 'complex_object')
+    assert.deepEqual(semantic.config?.allowedCurrencies, ['USD', 'EUR', 'GBP'])
+  })
+})
+
+test.group('Price Configuration Validation', () => {
+  test('should validate that defaultCurrency is required for decimal format', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'decimal',
+      // Missing defaultCurrency
+      decimalPlaces: 2,
+    }
+    const errors = validatePriceConfig(config)
+    assert.include(errors, 'defaultCurrency is required when storageFormat is not complex_object')
+  })
+
+  test('should validate that defaultCurrency is required for integer_cents format', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'integer_cents',
+      // Missing defaultCurrency
+      decimalPlaces: 2,
+    }
+    const errors = validatePriceConfig(config)
+    assert.include(errors, 'defaultCurrency is required when storageFormat is not complex_object')
+  })
+
+  test('should not require defaultCurrency for complex_object format', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'complex_object',
+      // No defaultCurrency needed
+      allowedCurrencies: ['USD', 'EUR'],
+    }
+    const errors = validatePriceConfig(config)
+    assert.notInclude(errors, 'defaultCurrency is required when storageFormat is not complex_object')
+  })
+
+  test('should validate that decimalPlaces is non-negative', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'decimal',
+      defaultCurrency: 'USD',
+      decimalPlaces: -1,
+    }
+    const errors = validatePriceConfig(config)
+    assert.include(errors, 'decimalPlaces must be non-negative')
+  })
+
+  test('should accept zero decimal places', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'decimal',
+      defaultCurrency: 'JPY',
+      decimalPlaces: 0,
+    }
+    const errors = validatePriceConfig(config)
+    assert.notInclude(errors, 'decimalPlaces must be non-negative')
+  })
+
+  test('should return empty array for valid config', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'decimal',
+      defaultCurrency: 'USD',
+      decimalPlaces: 2,
+      allowNegative: false,
+    }
+    const errors = validatePriceConfig(config)
+    assert.lengthOf(errors, 0)
+  })
+
+  test('should accumulate multiple validation errors', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'decimal',
+      // Missing defaultCurrency
+      decimalPlaces: -2, // Invalid decimal places
+    }
+    const errors = validatePriceConfig(config)
+    assert.lengthOf(errors, 2)
+    assert.include(errors, 'defaultCurrency is required when storageFormat is not complex_object')
+    assert.include(errors, 'decimalPlaces must be non-negative')
+  })
+})
+
+test.group('Price Presets', () => {
+  test('USD_DECIMAL preset should have correct configuration', ({ assert }) => {
+    const preset = PRICE_PRESETS.USD_DECIMAL
+    assert.equal(preset.id, SemanticType.Price)
+    assert.equal(preset.config?.storageFormat, 'decimal')
+    assert.equal(preset.config?.defaultCurrency, 'USD')
+    assert.equal(preset.config?.decimalPlaces, 2)
+    assert.equal(preset.config?.allowNegative, false)
+  })
+
+  test('USD_CENTS preset should have correct configuration', ({ assert }) => {
+    const preset = PRICE_PRESETS.USD_CENTS
+    assert.equal(preset.id, SemanticType.Price)
+    assert.equal(preset.config?.storageFormat, 'integer_cents')
+    assert.equal(preset.config?.defaultCurrency, 'USD')
+    assert.equal(preset.config?.decimalPlaces, 2)
+    assert.equal(preset.config?.allowNegative, false)
+  })
+
+  test('MULTI_CURRENCY preset should have correct configuration', ({ assert }) => {
+    const preset = PRICE_PRESETS.MULTI_CURRENCY
+    assert.equal(preset.id, SemanticType.Price)
+    assert.equal(preset.config?.storageFormat, 'complex_object')
+    assert.deepEqual(preset.config?.allowedCurrencies, ['USD', 'EUR', 'GBP', 'JPY', 'CAD'])
+    assert.equal(preset.config?.decimalPlaces, 2)
+    assert.equal(preset.config?.allowNegative, false)
+  })
+
+  test('WITH_NEGATIVES preset should have correct configuration', ({ assert }) => {
+    const preset = PRICE_PRESETS.WITH_NEGATIVES
+    assert.equal(preset.id, SemanticType.Price)
+    assert.equal(preset.config?.storageFormat, 'decimal')
+    assert.equal(preset.config?.defaultCurrency, 'USD')
+    assert.equal(preset.config?.decimalPlaces, 2)
+    assert.equal(preset.config?.allowNegative, true)
+  })
+
+  test('HIGH_PRECISION preset should have correct configuration', ({ assert }) => {
+    const preset = PRICE_PRESETS.HIGH_PRECISION
+    assert.equal(preset.id, SemanticType.Price)
+    assert.equal(preset.config?.storageFormat, 'decimal')
+    assert.equal(preset.config?.defaultCurrency, 'BTC')
+    assert.equal(preset.config?.decimalPlaces, 8)
+    assert.equal(preset.config?.allowNegative, false)
+  })
+
+  test('all presets should be valid price semantics', ({ assert }) => {
+    Object.values(PRICE_PRESETS).forEach((preset) => {
+      assert.isTrue(isPriceSemantic(preset))
+      // Validate each preset config
+      if (preset.config) {
+        const errors = validatePriceConfig(preset.config)
+        assert.lengthOf(errors, 0, `Preset ${preset.config.storageFormat} should have valid config`)
+      }
+    })
+  })
+})
+
+test.group('Price Currency Configuration', () => {
+  test('should support single currency with defaultCurrency', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'decimal',
+      defaultCurrency: 'EUR',
+      decimalPlaces: 2,
+    }
+    const semantic = createPriceSemantic(config)
+    assert.equal(semantic.config?.defaultCurrency, 'EUR')
+    assert.isUndefined(semantic.config?.allowedCurrencies)
+  })
+
+  test('should support multiple currencies with allowedCurrencies', ({ assert }) => {
+    const currencies = ['USD', 'EUR', 'GBP', 'JPY', 'CAD', 'AUD']
+    const config: PriceConfig = {
+      storageFormat: 'complex_object',
+      allowedCurrencies: currencies,
+      decimalPlaces: 2,
+    }
+    const semantic = createPriceSemantic(config)
+    assert.deepEqual(semantic.config?.allowedCurrencies, currencies)
+  })
+
+  test('should support currency validation toggle', ({ assert }) => {
+    const configWithValidation: PriceConfig = {
+      storageFormat: 'decimal',
+      defaultCurrency: 'USD',
+      validateCurrencyCode: true,
+    }
+    const configWithoutValidation: PriceConfig = {
+      storageFormat: 'decimal',
+      defaultCurrency: 'USD',
+      validateCurrencyCode: false,
+    }
+
+    const semanticWithValidation = createPriceSemantic(configWithValidation)
+    const semanticWithoutValidation = createPriceSemantic(configWithoutValidation)
+
+    assert.isTrue(semanticWithValidation.config?.validateCurrencyCode)
+    assert.isFalse(semanticWithoutValidation.config?.validateCurrencyCode)
+  })
+})
+
+test.group('Price Precision Configuration', () => {
+  test('should support standard 2 decimal places (USD, EUR)', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'decimal',
+      defaultCurrency: 'USD',
+      decimalPlaces: 2,
+    }
+    const semantic = createPriceSemantic(config)
+    assert.equal(semantic.config?.decimalPlaces, 2)
+  })
+
+  test('should support zero decimal places (JPY, KRW)', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'decimal',
+      defaultCurrency: 'JPY',
+      decimalPlaces: 0,
+    }
+    const semantic = createPriceSemantic(config)
+    assert.equal(semantic.config?.decimalPlaces, 0)
+  })
+
+  test('should support high precision (3 decimal places for BHD, KWD)', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'decimal',
+      defaultCurrency: 'BHD',
+      decimalPlaces: 3,
+    }
+    const semantic = createPriceSemantic(config)
+    assert.equal(semantic.config?.decimalPlaces, 3)
+  })
+
+  test('should support very high precision (cryptocurrencies)', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'decimal',
+      defaultCurrency: 'BTC',
+      decimalPlaces: 8,
+    }
+    const semantic = createPriceSemantic(config)
+    assert.equal(semantic.config?.decimalPlaces, 8)
+  })
+})
+
+test.group('Price Negative Values Configuration', () => {
+  test('should support disallowing negative values (default)', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'decimal',
+      defaultCurrency: 'USD',
+      allowNegative: false,
+    }
+    const semantic = createPriceSemantic(config)
+    assert.isFalse(semantic.config?.allowNegative)
+  })
+
+  test('should support allowing negative values (refunds, discounts)', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'decimal',
+      defaultCurrency: 'USD',
+      allowNegative: true,
+    }
+    const semantic = createPriceSemantic(config)
+    assert.isTrue(semantic.config?.allowNegative)
+  })
+})
+
+test.group('Price Metadata Configuration', () => {
+  test('should support custom metadata', ({ assert }) => {
+    const metadata = {
+      displayFormat: 'currency',
+      showCurrencySymbol: true,
+      rounding: 'standard',
+      customField: 'value',
+    }
+    const config: PriceConfig = {
+      storageFormat: 'decimal',
+      defaultCurrency: 'USD',
+      metadata,
+    }
+    const semantic = createPriceSemantic(config)
+    assert.deepEqual(semantic.config?.metadata, metadata)
+  })
+
+  test('should merge metadata with other config', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'complex_object',
+      allowedCurrencies: ['USD', 'EUR'],
+      decimalPlaces: 2,
+      metadata: {
+        source: 'external_api',
+        lastUpdated: '2023-01-01',
+      },
+    }
+    const semantic = createPriceSemantic(config)
+    assert.equal(semantic.config?.storageFormat, 'complex_object')
+    assert.deepEqual(semantic.config?.allowedCurrencies, ['USD', 'EUR'])
+    assert.equal(semantic.config?.decimalPlaces, 2)
+    assert.deepEqual(semantic.config?.metadata, {
+      source: 'external_api',
+      lastUpdated: '2023-01-01',
+    })
+  })
+})
+
+test.group('Price Cross-semantic Type Guards', () => {
+  test('should correctly identify different semantic types', ({ assert }) => {
+    const priceSemantic = createPriceSemantic()
+
+    // Mock other semantics for comparison
+    const emailSemantic: AppliedDataSemantic = { id: SemanticType.Email }
+    const statusSemantic: AppliedDataSemantic = { id: SemanticType.Status }
+    const userSemantic: AppliedDataSemantic = { id: SemanticType.User }
+
+    // Price semantic should only be identified as Price
+    assert.isTrue(isPriceSemantic(priceSemantic))
+    assert.isFalse(isPriceSemantic(emailSemantic))
+    assert.isFalse(isPriceSemantic(statusSemantic))
+    assert.isFalse(isPriceSemantic(userSemantic))
+  })
+})
+
+test.group('Price Real-world Use Cases', () => {
+  test('should configure for simple e-commerce store', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'decimal',
+      defaultCurrency: 'USD',
+      decimalPlaces: 2,
+      allowNegative: false,
+      validateCurrencyCode: true,
+    }
+    const semantic = createPriceSemantic(config)
+    const errors = validatePriceConfig(config)
+
+    assert.lengthOf(errors, 0)
+    assert.equal(semantic.config?.storageFormat, 'decimal')
+    assert.equal(semantic.config?.defaultCurrency, 'USD')
+    assert.isFalse(semantic.config?.allowNegative)
+  })
+
+  test('should configure for international marketplace', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'complex_object',
+      allowedCurrencies: ['USD', 'EUR', 'GBP', 'JPY', 'CAD', 'AUD'],
+      decimalPlaces: 2,
+      allowNegative: false,
+      validateCurrencyCode: true,
+    }
+    const semantic = createPriceSemantic(config)
+    const errors = validatePriceConfig(config)
+
+    assert.lengthOf(errors, 0)
+    assert.equal(semantic.config?.storageFormat, 'complex_object')
+    assert.isArray(semantic.config?.allowedCurrencies)
+    assert.lengthOf(semantic.config?.allowedCurrencies || [], 6)
+  })
+
+  test('should configure for financial system with precision', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'integer_cents',
+      defaultCurrency: 'USD',
+      decimalPlaces: 4,
+      allowNegative: true,
+      validateCurrencyCode: true,
+    }
+    const semantic = createPriceSemantic(config)
+    const errors = validatePriceConfig(config)
+
+    assert.lengthOf(errors, 0)
+    assert.equal(semantic.config?.storageFormat, 'integer_cents')
+    assert.equal(semantic.config?.decimalPlaces, 4)
+    assert.isTrue(semantic.config?.allowNegative)
+  })
+
+  test('should configure for cryptocurrency trading', ({ assert }) => {
+    const config: PriceConfig = {
+      storageFormat: 'decimal',
+      defaultCurrency: 'BTC',
+      decimalPlaces: 8,
+      allowNegative: false,
+      validateCurrencyCode: false, // Custom crypto currency
+    }
+    const semantic = createPriceSemantic(config)
+    const errors = validatePriceConfig(config)
+
+    assert.lengthOf(errors, 0)
+    assert.equal(semantic.config?.defaultCurrency, 'BTC')
+    assert.equal(semantic.config?.decimalPlaces, 8)
+    assert.isFalse(semantic.config?.validateCurrencyCode)
+  })
+})

package/tests/unit/modeling/definitions/public-unique-name.spec.ts

@@ -0,0 +1,38 @@
+import { test } from '@japa/runner'
+import {
+  createPublicUniqueNameSemantic,
+  isPublicUniqueNameSemantic,
+  DEFAULT_PUBLIC_UNIQUE_NAME_CONFIG,
+  type PublicUniqueNameConfig,
+} from '../../../../src/modeling/definitions/PublicUniqueName.js'
+import { SemanticType, type AppliedDataSemantic } from '../../../../src/modeling/Semantics.js'
+
+test.group('PublicUniqueName Semantic Configuration', () => {
+  test('should create semantic with default config', ({ assert }) => {
+    const semantic = createPublicUniqueNameSemantic()
+    assert.equal(semantic.id, SemanticType.PublicUniqueName)
+    assert.deepEqual(semantic.config, DEFAULT_PUBLIC_UNIQUE_NAME_CONFIG)
+  })
+
+  test('should create semantic with custom config', ({ assert }) => {
+    const config: PublicUniqueNameConfig = {
+      sourceField: 'title',
+      separator: '-',
+      maxLength: 50,
+    }
+    const semantic = createPublicUniqueNameSemantic(config)
+    assert.equal(semantic.id, SemanticType.PublicUniqueName)
+    assert.deepEqual(semantic.config, { ...DEFAULT_PUBLIC_UNIQUE_NAME_CONFIG, ...config })
+  })
+
+  test('should identify public unique name semantic', ({ assert }) => {
+    const semantic = createPublicUniqueNameSemantic()
+    assert.isTrue(isPublicUniqueNameSemantic(semantic))
+  })
+
+  test('should not identify non-public-unique-name semantic', ({ assert }) => {
+    // Simulate a different semantic
+    const fakeSemantic: AppliedDataSemantic = { id: SemanticType.Email, config: {} }
+    assert.isFalse(isPublicUniqueNameSemantic(fakeSemantic))
+  })
+})