@api-client/core 0.15.1 → 0.16.0

package/src/modeling/definitions/Price.ts

@@ -0,0 +1,180 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Supported storage formats for monetary values.
+ */
+export type PriceStorageFormat = 'decimal' | 'integer_cents' | 'complex_object'
+
+/**
+ * Configuration options for the Price semantic.
+ * Controls monetary value storage, validation, currency handling, and precision.
+ */
+export interface PriceConfig {
+  /**
+   * How the monetary value is stored in the database.
+   *
+   * - 'decimal': Store as DECIMAL/NUMERIC type (e.g., 19.99)
+   * - 'integer_cents': Store as INTEGER in smallest currency unit (e.g., 1999 for $19.99)
+   * - 'complex_object': Store as JSON/JSONB with amount and currency (e.g., {"amount": 1999, "currency": "USD"})
+   */
+  storageFormat?: PriceStorageFormat
+
+  /**
+   * Default currency code (ISO 4217) when not specified.
+   * Required when using 'decimal' or 'integer_cents' format.
+   */
+  defaultCurrency?: string
+
+  /**
+   * List of allowed currency codes (ISO 4217).
+   * If not specified, all valid ISO 4217 currencies are allowed.
+   */
+  allowedCurrencies?: string[]
+
+  /**
+   * Number of decimal places for precision.
+   * Default: 2 (for most currencies like USD, EUR)
+   * Some currencies may need 0 (JPY, KRW) or 3 (BHD, KWD)
+   */
+  decimalPlaces?: number
+
+  /**
+   * Whether negative values are allowed (for refunds, discounts, etc.).
+   */
+  allowNegative?: boolean
+
+  /**
+   * Whether to automatically validate currency codes against ISO 4217.
+   */
+  validateCurrencyCode?: boolean
+
+  /**
+   * Custom metadata for the price field.
+   */
+  metadata?: Record<string, unknown>
+
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for Price semantic.
+ */
+export interface AppliedPriceSemantic extends AppliedDataSemantic {
+  id: SemanticType.Price
+  config?: PriceConfig
+}
+
+/**
+ * Type guard to check if a semantic is a Price semantic.
+ */
+export const isPriceSemantic = (semantic: AppliedDataSemantic): semantic is AppliedPriceSemantic => {
+  return semantic.id === SemanticType.Price
+}
+
+/**
+ * Helper function to create a Price semantic with configuration.
+ */
+export const createPriceSemantic = (config: PriceConfig = {}): AppliedPriceSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_PRICE_CONFIG,
+    ...config,
+  }
+
+  // Merge metadata separately
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.Price,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for Price semantic.
+ * Optimized for common e-commerce use cases with USD currency.
+ */
+export const DEFAULT_PRICE_CONFIG: PriceConfig = {
+  storageFormat: 'decimal',
+  defaultCurrency: 'USD',
+  decimalPlaces: 2,
+  allowNegative: false,
+  validateCurrencyCode: true,
+}
+
+/**
+ * Predefined configurations for common use cases.
+ */
+export const PRICE_PRESETS = {
+  /**
+   * Simple USD decimal storage - good for most e-commerce sites.
+   */
+  USD_DECIMAL: createPriceSemantic({
+    storageFormat: 'decimal',
+    defaultCurrency: 'USD',
+    decimalPlaces: 2,
+    allowNegative: false,
+  }),
+
+  /**
+   * Integer cents storage - avoids floating point issues, good for financial calculations.
+   */
+  USD_CENTS: createPriceSemantic({
+    storageFormat: 'integer_cents',
+    defaultCurrency: 'USD',
+    decimalPlaces: 2,
+    allowNegative: false,
+  }),
+
+  /**
+   * Multi-currency support with complex object storage.
+   */
+  MULTI_CURRENCY: createPriceSemantic({
+    storageFormat: 'complex_object',
+    allowedCurrencies: ['USD', 'EUR', 'GBP', 'JPY', 'CAD'],
+    decimalPlaces: 2,
+    allowNegative: false,
+  }),
+
+  /**
+   * Configuration that allows negative values for refunds, discounts, etc.
+   */
+  WITH_NEGATIVES: createPriceSemantic({
+    storageFormat: 'decimal',
+    defaultCurrency: 'USD',
+    decimalPlaces: 2,
+    allowNegative: true,
+  }),
+
+  /**
+   * High-precision configuration for cryptocurrency or precious metals.
+   */
+  HIGH_PRECISION: createPriceSemantic({
+    storageFormat: 'decimal',
+    defaultCurrency: 'BTC',
+    decimalPlaces: 8,
+    allowNegative: false,
+  }),
+} as const
+
+/**
+ * Helper function to validate a price configuration.
+ */
+export const validatePriceConfig = (config: PriceConfig): string[] => {
+  const errors: string[] = []
+
+  if (config.storageFormat !== 'complex_object' && !config.defaultCurrency) {
+    errors.push('defaultCurrency is required when storageFormat is not complex_object')
+  }
+
+  if (config.decimalPlaces !== undefined && config.decimalPlaces < 0) {
+    errors.push('decimalPlaces must be non-negative')
+  }
+
+  return errors
+}

package/src/modeling/definitions/PublicUniqueName.ts

@@ -0,0 +1,98 @@
+import type { AppliedDataSemantic } from '../Semantics.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Configuration options for the PublicUniqueName (slug) semantic.
+ * Controls how slugs are generated and validated.
+ */
+export interface PublicUniqueNameConfig {
+  /**
+   * The source field to generate the slug from (e.g., 'title').
+   * Default to the field that is annotated with the Title semantic.
+   */
+  sourceField?: string
+  /**
+   * Separator character to use in the slug (default: '-').
+   */
+  separator?: string
+  /**
+   * Maximum length of the slug (default: 64).
+   */
+  maxLength?: number
+  /**
+   * Whether the slug is case sensitive (default: false).
+   */
+  caseSensitive?: boolean
+  /**
+   * Whether to allow Unicode characters in the slug (default: false).
+   */
+  allowUnicode?: boolean
+  /**
+   * Name of a custom generator function to use for slug creation.
+   */
+  customGenerator?: string
+  /**
+   * Whether to allow duplicate slugs (default: false).
+   */
+  allowDuplicates?: boolean
+  /**
+   * Fallback field to use if the source field is empty or invalid.
+   */
+  fallbackField?: string
+  /**
+   * Custom metadata for the slug field.
+   */
+  metadata?: Record<string, unknown>
+  /**
+   * Index signature to allow additional properties.
+   */
+  [key: string]: unknown
+}
+
+/**
+ * Type-safe configuration for PublicUniqueName semantic.
+ */
+export interface AppliedPublicUniqueNameSemantic extends AppliedDataSemantic {
+  id: SemanticType.PublicUniqueName
+  config?: PublicUniqueNameConfig
+}
+
+/**
+ * Type guard to check if a semantic is a PublicUniqueName semantic.
+ */
+export const isPublicUniqueNameSemantic = (
+  semantic: AppliedDataSemantic
+): semantic is AppliedPublicUniqueNameSemantic => {
+  return semantic.id === SemanticType.PublicUniqueName
+}
+
+/**
+ * Helper function to create a PublicUniqueName semantic with configuration.
+ */
+export const createPublicUniqueNameSemantic = (
+  config: PublicUniqueNameConfig = {}
+): AppliedPublicUniqueNameSemantic => {
+  const mergedConfig = {
+    ...DEFAULT_PUBLIC_UNIQUE_NAME_CONFIG,
+    ...config,
+  }
+  if (config.metadata) {
+    mergedConfig.metadata = { ...config.metadata }
+  }
+
+  return {
+    id: SemanticType.PublicUniqueName,
+    config: mergedConfig,
+  }
+}
+
+/**
+ * Default configuration for PublicUniqueName semantic.
+ */
+export const DEFAULT_PUBLIC_UNIQUE_NAME_CONFIG: PublicUniqueNameConfig = {
+  separator: '-',
+  maxLength: 64,
+  caseSensitive: false,
+  allowUnicode: false,
+  allowDuplicates: false,
+}

package/src/modeling/definitions/SKU.examples.md

@@ -0,0 +1,230 @@
+# SKU Semantic Examples
+
+This document provides examples of how to use the SKU semantic with different configurations.
+
+## Basic Usage
+
+```typescript
+import { createSKUSemantic, SKU_PRESETS } from './SKU.js'
+
+// Simple SKU with default settings
+const basicSKU = createSKUSemantic()
+
+// Using a preset for product catalogs
+const productSKU = SKU_PRESETS.PRODUCT_STANDARD
+```
+
+## Configuration Examples
+
+### 1. Standard Product Catalog
+
+```typescript
+const productCatalogSKU = createSKUSemantic({
+  validationMode: 'strict',
+  caseMode: 'uppercase',
+  prefix: 'PROD-',
+  enforceUniqueness: true,
+  validateReservedWords: true,
+})
+```
+
+### 2. Simple Inventory System
+
+```typescript
+const simpleSKU = createSKUSemantic({
+  validationMode: 'lenient',
+  caseMode: 'preserve',
+  enforceUniqueness: true,
+})
+```
+
+### 3. Auto-generating SKUs
+
+```typescript
+const autoGeneratedSKU = createSKUSemantic({
+  validationMode: 'strict',
+  caseMode: 'uppercase',
+  autoGenerate: true,
+  autoGenerateSource: 'name', // Generate from product name
+  enforceUniqueness: true,
+})
+```
+
+### 4. Custom Pattern Validation
+
+```typescript
+const customPatternSKU = createSKUSemantic({
+  validationMode: 'custom',
+  customPattern: '^[A-Z]{3}-\\d{4}-[A-Z]{2}$', // Format: ABC-1234-XY
+  caseMode: 'uppercase',
+  enforceUniqueness: true,
+})
+```
+
+### 5. Flexible Multi-category System
+
+```typescript
+const flexibleSKU = createSKUSemantic({
+  validationMode: 'lenient',
+  caseMode: 'preserve',
+  enforceUniqueness: true,
+  validateReservedWords: false, // Allow more flexibility
+})
+```
+
+## Storage Format Details
+
+### Database Schema Generation
+
+The runtime will generate appropriate database schemas with unique constraints:
+
+```sql
+CREATE TABLE products (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(255),
+  sku VARCHAR(50) UNIQUE NOT NULL,
+  description TEXT
+);
+
+-- Automatically creates unique index
+CREATE UNIQUE INDEX idx_products_sku ON products(sku);
+
+-- For case-insensitive uniqueness (depending on configuration)
+CREATE UNIQUE INDEX idx_products_sku_lower ON products(LOWER(sku));
+```
+
+### Case Transformation Examples
+
+```typescript
+// Uppercase transformation
+const uppercaseSKU = createSKUSemantic({ caseMode: 'uppercase' })
+// Input: "prod-123" → Stored: "PROD-123"
+
+// Lowercase transformation  
+const lowercaseSKU = createSKUSemantic({ caseMode: 'lowercase' })
+// Input: "PROD-123" → Stored: "prod-123"
+
+// Preserve original case
+const preserveCaseSKU = createSKUSemantic({ caseMode: 'preserve' })
+// Input: "Prod-123" → Stored: "Prod-123"
+```
+
+## Validation Examples
+
+### Strict Validation
+
+```typescript
+const strictSKU = createSKUSemantic({ validationMode: 'strict' })
+
+// Valid SKUs
+strictSKU.validate('PRODUCT123')  // ✓ Valid
+strictSKU.validate('PROD-123')    // ✓ Valid
+strictSKU.validate('PROD_123')    // ✓ Valid
+
+// Invalid SKUs
+strictSKU.validate('PROD.123')    // ✗ Contains dot
+strictSKU.validate('PROD@123')    // ✗ Contains special character
+strictSKU.validate('PROD 123')    // ✗ Contains space
+```
+
+### Lenient Validation
+
+```typescript
+const lenientSKU = createSKUSemantic({ validationMode: 'lenient' })
+
+// Valid SKUs
+lenientSKU.validate('PRODUCT123')  // ✓ Valid
+lenientSKU.validate('PROD-123')    // ✓ Valid
+lenientSKU.validate('PROD.123')    // ✓ Valid (dots allowed)
+
+// Invalid SKUs
+lenientSKU.validate('PROD@123')    // ✗ Special characters not allowed
+lenientSKU.validate('PROD#123')    // ✗ Hash not allowed
+```
+
+### Custom Pattern Validation
+
+```typescript
+const customSKU = createSKUSemantic({
+  validationMode: 'custom',
+  customPattern: '^[A-Z]{2}\\d{4}$' // Two letters followed by four digits
+})
+
+// Valid SKUs
+customSKU.validate('AB1234')  // ✓ Valid
+customSKU.validate('XY9999')  // ✓ Valid
+
+// Invalid SKUs
+customSKU.validate('ABC123')   // ✗ Wrong format
+customSKU.validate('ab1234')   // ✗ Lowercase letters
+customSKU.validate('A1234')    // ✗ Only one letter
+```
+
+## Reserved Words
+
+The SKU semantic includes protection against common reserved values:
+
+```typescript
+const skuConfig = createSKUSemantic({
+  validateReservedWords: true,
+  reservedValues: ['ADMIN', 'TEST', 'NULL', 'DEFAULT', 'SAMPLE']
+})
+
+// These will be rejected
+skuConfig.validate('ADMIN')   // ✗ Reserved word
+skuConfig.validate('test')    // ✗ Reserved word (case-insensitive)
+skuConfig.validate('NULL')    // ✗ Reserved word
+```
+
+## Auto-generation Behavior
+
+When `autoGenerate` is enabled, the runtime automatically creates SKUs:
+
+```typescript
+const autoSKU = createSKUSemantic({
+  autoGenerate: true,
+  autoGenerateSource: 'name',
+  prefix: 'PROD-',
+  caseMode: 'uppercase'
+})
+
+// For a product named "Blue Widget"
+// Generated SKU might be: "PROD-BLUE-WIDGET" or "PROD-BLUE-WIDGET-001"
+```
+
+## Error Handling
+
+```typescript
+import { validateSKUConfig, validateSKUValue } from './SKU.js'
+
+// Validate configuration
+const configErrors = validateSKUConfig({
+  validationMode: 'custom'  // Invalid: missing customPattern
+})
+console.log(configErrors) // ['customPattern is required when validationMode is custom']
+
+// Validate SKU values
+const valueErrors = validateSKUValue('TEST')
+console.log(valueErrors) // ['SKU cannot use reserved value: TEST']
+```
+
+## Integration with Domain Entities
+
+```typescript
+// In your domain model
+const productEntity = domain.addEntity({
+  name: 'Product',
+  properties: [
+    {
+      name: 'sku',
+      type: 'string',
+      semantics: [createSKUSemantic({
+        validationMode: 'strict',
+        caseMode: 'uppercase',
+        prefix: 'PROD-',
+        enforceUniqueness: true
+      })]
+    }
+  ]
+})
+```