Core Type Mapping Guide

Overview

This guide provides the mapping between OpenAPI string formats and their corresponding TypeScript type classes for use in Tasks 5, 7, 8, and 9.

🚨 Critical Usage Rules

• Task 5: Use these mappings when creating OpenAPI specifications - set the correct format field
• Task 7: Use these mappings in data transformation and validation
• Task 8 & 9: Use these mappings for type assertions in tests (e.g., instanceof Email, instanceof UUID)
• String Conversion: All types support .toString() method and template literal interpolation
• Import Sources: Import types from the specified packages, not from Node.js built-ins

AWS Types (@zerobias-org/types-amazon-js)

| String Format | TypeScript Type | Usage Example | |---------------|------------------|---------------| | arn | Arn | toEnum(Arn, value) or new Arn(value) | | awsPartition | AwsPartition | toEnum(AwsPartition, value) | | awsService | AwsService | toEnum(AwsService, value) | | awsImageId | AwsImageId | toEnum(AwsImageId, value) | | awsAccessPolicy | AwsAccessPolicy | new AwsAccessPolicy(value) | | awsAccessPolicyStatement | AwsAccessPolicyStatement | new AwsAccessPolicyStatement(value) | | awsAccessPolicyStatementCondition | AwsAccessPolicyStatementCondition | new AwsAccessPolicyStatementCondition(value) | | awsAccessPolicyStatementEffect | AwsAccessPolicyStatementEffect | toEnum(AwsAccessPolicyStatementEffect, value) | | awsAccessPolicyStatementOperator | AwsAccessPolicyStatementOperator | toEnum(AwsAccessPolicyStatementOperator, value) |

Microsoft Azure Types (@zerobias-org/types-microsoft-js)

| String Format | TypeScript Type | Usage Example | |---------------|------------------|---------------| | azureVmSize | AzureVmSize | toEnum(AzureVmSize, value) | | azureResourceProvider | AzureResourceProvider | toEnum(AzureResourceProvider, value) | | azureResource | AzureResource | new AzureResource(value) | | azureResourceInfo | AzureResourceInfo | new AzureResourceInfo(value) | | azureResourceType | AzureResourceType | toEnum(AzureResourceType, value) | | azureResourcePlan | AzureResourcePlan | new AzureResourcePlan(value) | | azureResourceSku | AzureResourceSku | new AzureResourceSku(value) | | azureResourceSkuTier | AzureResourceSkuTier | toEnum(AzureResourceSkuTier, value) | | azureResourceIdentity | AzureResourceIdentity | new AzureResourceIdentity(value) | | azureResourceIdentityType | AzureResourceIdentityType | toEnum(AzureResourceIdentityType, value) |

Google Cloud Types (@zerobias-org/types-google-js)

| String Format | TypeScript Type | Usage Example | |---------------|------------------|---------------| | gcpAccessPolicy | GcpAccessPolicy | new GcpAccessPolicy(value) | | gcpAccessPolicyAuditConfig | GcpAccessPolicyAuditConfig | new GcpAccessPolicyAuditConfig(value) | | gcpAccessPolicyAuditLogConfig | GcpAccessPolicyAuditLogConfig | new GcpAccessPolicyAuditLogConfig(value) | | gcpAccessPolicyAuditLogConfigType | GcpAccessPolicyAuditLogConfigType | toEnum(GcpAccessPolicyAuditLogConfigType, value) | | gcpAccessPolicyBinding | GcpAccessPolicyBinding | new GcpAccessPolicyBinding(value) | | gcpAccessPolicyBindingCondition | GcpAccessPolicyBindingCondition | new GcpAccessPolicyBindingCondition(value) | | gcpAccessPolicyVersion | GcpAccessPolicyVersion | toEnum(GcpAccessPolicyVersion, value) |

Core Types (@zerobias-org/types-core-js)

Binary/Encoding

| String Format | TypeScript Type | Usage Example | |---------------|------------------|---------------| | byte | Byte | new Byte(value) | | b64 | Byte | new Byte(value) | | base64 | Byte | new Byte(value) |

Networking

| String Format | TypeScript Type | Usage Example | |---------------|------------------|---------------| | cidr | Cidr | new Cidr(value) | | ipAddress | IpAddress | new IpAddress(value) | | ip | IpAddress | new IpAddress(value) | | ipv4 | IpAddress | new IpAddress(value) | | ipv6 | IpAddress | new IpAddress(value) | | mac | MacAddress | new MacAddress(value) | | macaddr | MacAddress | new MacAddress(value) | | macAddress | MacAddress | new MacAddress(value) | | hostname | Hostname | new Hostname(value) |

Date/Time

| String Format | TypeScript Type | Usage Example | |---------------|------------------|---------------| | date-time | Date | new Date(value) | | time | Date | new Date(value) | | timestamp | Date | new Date(value) | | date | Date | new Date(value) | | duration | Duration | new Duration(value) |

Numeric

| String Format | TypeScript Type | Usage Example | |---------------|------------------|---------------| | double | number | Number(value) | | float | number | Number(value) | | int32 | number | Number(value) | | int64 | number | Number(value) | | integer | number | Number(value) |

Communication/Identity

| String Format | TypeScript Type | Usage Example | |---------------|------------------|---------------| | email | Email | new Email(value) | | phoneNumber | PhoneNumber | new PhoneNumber(value) | | phone | PhoneNumber | new PhoneNumber(value) | | url | URL | new URL(value) | | uri | URL | new URL(value) |

Identifiers

| String Format | TypeScript Type | Usage Example | |---------------|------------------|---------------| | uuid | UUID | new UUID(value) | | guid | UUID | new UUID(value) | | objectId | ObjectId | new ObjectId(value) |

Security

| String Format | TypeScript Type | Usage Example | |---------------|------------------|---------------| | password | string | Direct string usage | | secret | string | Direct string usage | | token | string | Direct string usage | | apiKey | string | Direct string usage |

Geographic

| String Format | TypeScript Type | Usage Example | |---------------|------------------|---------------| | latitude | Latitude | new Latitude(value) | | longitude | Longitude | new Longitude(value) | | geoPoint | GeoPoint | new GeoPoint(lat, lon) | | country | Country | toEnum(Country, value) | | countryCode | Country | toEnum(Country, value) | | language | Language | toEnum(Language, value) | | languageCode | Language | toEnum(Language, value) | | currency | Currency | toEnum(Currency, value) | | currencyCode | Currency | toEnum(Currency, value) |

File/Media

| String Format | TypeScript Type | Usage Example | |---------------|------------------|---------------| | mimeType | MimeType | toEnum(MimeType, value) | | fileExtension | FileExtension | toEnum(FileExtension, value) | | path | Path | new Path(value) | | filePath | Path | new Path(value) |

Business/Domain

| String Format | TypeScript Type | Usage Example | |---------------|------------------|---------------| | ssn | Ssn | new Ssn(value) | | tin | Tin | new Tin(value) | | iban | Iban | new Iban(value) | | creditCard | CreditCard | new CreditCard(value) | | postalCode | PostalCode | new PostalCode(value) | | zipCode | PostalCode | new PostalCode(value) |

Complete Type Mapping Reference Table

Consolidated Quick Reference

| Format | Package | Type | Constructor Pattern | |--------|---------|------|-------------------| | uuid | @zerobias-org/types-core-js | UUID | map(UUID, value) | | email | @zerobias-org/types-core-js | Email | map(Email, value) | | url | @zerobias-org/types-core-js | URL | map(URL, value) | | date-time | Native | Date | map(Date, value) | | ipAddress | @zerobias-org/types-core-js | IpAddress | map(IpAddress, value) | | phoneNumber | @zerobias-org/types-core-js | PhoneNumber | map(PhoneNumber, value) | | arn | @zerobias-org/types-amazon-js | Arn | map(Arn, value) | | cidr | @zerobias-org/types-core-js | Cidr | map(Cidr, value) | | duration | @zerobias-org/types-core-js | Duration | map(Duration, value) | | base64 | @zerobias-org/types-core-js | Byte | map(Byte, value) |

Usage Patterns by Task

Task 5: OpenAPI Specification

# Use format field to specify type
properties:
  id:
    type: string
    format: uuid  # → Will generate UUID type
  email:
    type: string
    format: email  # → Will generate Email type
  createdAt:
    type: string
    format: date-time  # → Will generate Date type

Task 7: Implementation (Mappers)

import { map, toEnum } from '@zerobias-org/util-hub-module-utils';
import { UUID, Email, URL } from '@zerobias-org/types-core-js';  // NEVER from Node.js!

export function toUserInfo(raw: any): UserInfo {
  return {
    id: map(UUID, raw.id),
    email: map(Email, raw.email),
    website: map(URL, raw.website_url),
    createdAt: map(Date, raw.created_at),
    status: toEnum(StatusEnum, raw.status)
  };
}

Task 8 & 9: Testing

import { UUID, Email } from '@zerobias-org/types-core-js';

it('should return user with correct types', () => {
  const user = await getUser('123');

  expect(user.id).to.be.instanceof(UUID);
  expect(user.email).to.be.instanceof(Email);
  expect(user.createdAt).to.be.instanceof(Date);
});

String Conversion Support

All custom types support string conversion:

const email = new Email('user@example.com');

// Direct toString()
const emailString = email.toString();  // "user@example.com"

// Template literal (automatic conversion)
const message = `User email: ${email}`;  // "User email: user@example.com"

// JSON serialization
JSON.stringify({ email });  // {"email":"user@example.com"}

Package Import Requirements

Required Dependencies

{
  "dependencies": {
    "@zerobias-org/types-core-js": "*",
    "@zerobias-org/util-hub-module-utils": "*"
  },
  "devDependencies": {
    "@zerobias-org/types-amazon-js": "*",  // If using AWS
    "@zerobias-org/types-microsoft-js": "*",  // If using Azure
    "@zerobias-org/types-google-js": "*"  // If using GCP
  }
}

Common Mistakes to Avoid

❌ WRONG - Using Node.js built-ins

import { URL } from 'url';  // WRONG!
import { URL } from 'node:url';  // WRONG!

✅ CORRECT - Using core types

import { URL } from '@zerobias-org/types-core-js';  // CORRECT!

❌ WRONG - Direct enum instantiation

const status = new StatusEnum('active');  // WRONG - constructor is private!

✅ CORRECT - Using toEnum

const status = toEnum(StatusEnum, 'active');  // CORRECT!

❌ WRONG - Manual type conversion

const uuid = raw.id as UUID;  // WRONG - no validation!

✅ CORRECT - Using map function

const uuid = map(UUID, raw.id);  // CORRECT - validates and converts!

Priority Rules

1. Always use core types over native JavaScript types when available
2. Import from correct package - never from Node.js built-ins
3. Use map() for type conversion - provides validation
4. Use toEnum() for enums - never instantiate directly
5. All types support .toString() - use for string conversion

| String Format | TypeScript Type | Usage Example | |---------------|------------------|---------------| | email | Email | new Email(value) | | phoneNumber | PhoneNumber | new PhoneNumber(value) | | phone | PhoneNumber | new PhoneNumber(value) |

Web/Protocol

| String Format | TypeScript Type | Usage Example | |---------------|------------------|---------------| | url | URL | new URL(value) | | uri | URL | new URL(value) | | uuid | UUID | new UUID(value) | | mimeType | MimeType | new MimeType(value) |

Versioning

| String Format | TypeScript Type | Usage Example | |---------------|------------------|---------------| | semver | Semver | new Semver(value) | | versionRange | VersionRange | new VersionRange(value) |

Misc

| String Format | TypeScript Type | Usage Example | |---------------|------------------|---------------| | nmtoken | Nmtoken | new Nmtoken(value) | | password | string | String(value) |

Usage Patterns

Task 5: OpenAPI Specification

properties:
  email_address:
    type: string
    format: email  # Maps to Email type
  website_url:
    type: string
    format: url    # Maps to URL type
  user_id:
    type: string
    format: uuid   # Maps to UUID type

Task 7: Data Transformation

import { Email, URL, UUID } from '@zerobias-org/types-core-js';
import { map } from '@zerobias-org/util-hub-module-utils';

function mapUser(raw: any): User {
  return {
    id: map(UUID, raw.user_id),
    email: map(Email, raw.email_address),
    website: map(URL, raw.website_url)
  };
}

Task 8 & 9: Test Assertions

import { Email, URL, UUID } from '@zerobias-org/types-core-js';

// Test assertions
expect(user.id).to.be.instanceof(UUID);
expect(user.email).to.be.instanceof(Email);
expect(user.website).to.be.instanceof(URL);

String Conversion Examples

// All types support toString() and template literals
const email = new Email('user@example.com');
const emailString = email.toString();
const message = `User email: ${email}`;

const uuid = new UUID('123e4567-e89b-12d3-a456-426614174000');
const uuidString = uuid.toString();
const log = `Processing user ${uuid}`;

Package Import Requirements

🚨 CRITICAL: Always import from the specified packages:

// Core types - ALWAYS import from @zerobias-org/types-core-js
import { URL, UUID, Email, IpAddress } from '@zerobias-org/types-core-js';

// AWS types
import { Arn, AwsService } from '@zerobias-org/types-amazon-js';

// Azure types  
import { AzureVmSize, AzureResource } from '@zerobias-org/types-microsoft-js';

// Google Cloud types
import { GcpAccessPolicy } from '@zerobias-org/types-google-js';

// NEVER import URL from Node.js built-ins
// ❌ import { URL } from 'url';  // WRONG
// ✅ import { URL } from '@zerobias-org/types-core-js';  // CORRECT

Validation and Error Handling

All typed values can be validated and will throw appropriate errors for invalid formats:

try {
  const email = new Email('invalid-email');  // Throws validation error
} catch (error) {
  // Handle validation error
}

// Safe validation with try-catch in mappers
function safeMapEmail(raw: string): Email | null {
  try {
    return new Email(raw);
  } catch {
    return null;  // Or handle as appropriate for your use case
  }
}