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

``bash
pnpm add @verisure-italy/zipcode-types
`

Types

$3

Represents a geographic area with zip code information.

`typescript
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:

`typescript
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
})
`

$3

Represents an enabled zip code.

`typescript
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:

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

Usage Examples

$3

`typescript
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)
})
`

$3

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

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

// Validation is handled automatically by router-middleware
`

$3

`typescript
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.

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

License

Internal Verisure Italy package