ZipCode Types

TypeScript types and Zod schemas for ZipCode service entities. This package provides type-safe definitions for areas and enabled zip codes.

Features

• ✅ Type-Safe - Full TypeScript support with Zod runtime validation
• ✅ Shared Types - Built on top of @verisure-italy/shared-types
• ✅ Runtime Validation - Zod schemas for request/response validation
• ✅ Tree-Shakeable - ESM and CJS support for optimal bundle size

Installation

pnpm add @verisure-italy/zipcode-types

Types

Area

Represents a geographic area with zip code information.

import { Area, areaSchema } from '@verisure-italy/zipcode-types'

// TypeScript type
const area: Area = {
  id: '123e4567-e89b-12d3-a456-426614174000',
  city: 'Milano',
  province: 'MI',
  region: 'Lombardia',
  town: 'Milano',
  zipCode: '20100',
}

// Runtime validation with Zod
const result = areaSchema.safeParse(data)
if (result.success) {
  const validArea: Area = result.data
}

Schema:

const areaSchema = z.object({
  id: z.uuid(),                                              // UUID v4
  city: z.string().min(2, 'city.required'),                 // Min 2 chars
  province: z.string().min(2).max(3),                       // 2-3 chars (e.g., MI, RM)
  region: z.string().min(2, 'region.required'),            // Min 2 chars
  town: z.string().min(2, 'town.required'),                // Min 2 chars
  zipCode: zipCodeSchema,                                    // From shared-types
})

Enabled

Represents an enabled zip code.

import { Enabled, enabledSchema } from '@verisure-italy/zipcode-types'

// TypeScript type
const enabled: Enabled = {
  zipCode: '20100',
}

// Runtime validation with Zod
const result = enabledSchema.safeParse(data)
if (result.success) {
  const validEnabled: Enabled = result.data
}

Schema:

const enabledSchema = z.object({
  zipCode: zipCodeSchema,  // From shared-types
})

Usage Examples

Express Route with Validation

import express from 'express'
import { areaSchema, type Area } from '@verisure-italy/zipcode-types'

const router = express.Router()

router.post('/areas', async (req, res) => {
  // Validate request body
  const result = areaSchema.safeParse(req.body)
  
  if (!result.success) {
    return res.status(400).json({ 
      error: 'Invalid area data',
      details: result.error.issues 
    })
  }
  
  const area: Area = result.data
  // ... save to database ...
  
  res.json(area)
})

With Router Middleware

import { createRestResource } from '@verisure-italy/router-middleware'
import { areaSchema, type Area } from '@verisure-italy/zipcode-types'

const areaResource = createRestResource<Area>({
  name: 'area',
  schema: areaSchema,
  // ... repository methods ...
})

// Validation is handled automatically by router-middleware

Type Guards

import { areaSchema, type Area } from '@verisure-italy/zipcode-types'

function isValidArea(data: unknown): data is Area {
  return areaSchema.safeParse(data).success
}

// Usage
if (isValidArea(unknownData)) {
  // TypeScript knows this is an Area
  console.log(unknownData.city)
}

Dependencies

• @verisure-italy/shared-types - Provides zipCodeSchema and other shared types
• zod ^4.1.12 - Runtime validation library

Related Packages

• @verisure-italy/shared-types - Shared types across services
• @verisure-italy/router-middleware - REST resource creation with validation
• @verisure-italy/error-handler-middleware - Handles validation errors

TypeScript Configuration

This package is built with TypeScript 5.9+ and exports both type definitions and runtime schemas.

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "module": "ESNext",
    "target": "ES2022"
  }
}

License

Internal Verisure Italy package