@tamnt-work/nuxt-mapper
TypeScript icon, indicating that this package has built-in type declarations

1.4.4 • Public • Published

@tamnt-work/nuxt-mapper

npm version npm downloads License Nuxt

A powerful data mapper and converter module for Nuxt 3 that helps you transform data between different formats from backend to frontend using schema definitions.

Features

  • 🚀 Schema-driven development
  • 🔄 Automatic model and DTO generation
  • 📝 Type-safe data transformations
  • 🔍 Real-time schema watching
  • 🛠 CLI tools for code generation
  • ⚡️ Hot reload support
  • ✨ Zod-powered form validation
  • 🌐 i18n support for validation messages

Installation

# Using package manager of choice
pnpm add @tamnt-work/nuxt-mapper
yarn add @tamnt-work/nuxt-mapper
npm install @tamnt-work/nuxt-mapper
bun add @tamnt-work/nuxt-mapper

# Optional: Install zod if using form validation
pnpm add zod
yarn add zod
npm install zod
bun add zod

Setup

Add to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@tamnt-work/nuxt-mapper'],
  // Add services directory to auto-imports
  imports: {
    dirs: ['services']
  }
  dataMapper: {
    // Enable watch mode in development
    watch: true,
    // Enable ESLint auto-fix for generated files
    fixEslint: true,
    // Custom mappers directory (default: './mappers')
    mappersDir: './mappers',
    // Custom i18n import path (default: '@/utils/i18n')
    i18nImportPath: '@/locales/i18n',
  }
})

Usage

1. Model Schema Definition

First, initialize the schema files using the CLI:

# Initialize model schema
npx tw mapper init

# Initialize form schema
npx tw form init

This will create the following files:

  • mappers/schema.tw: Model schema definition
  • mappers/form.tw: Form validation schema

Then modify the schema files according to your needs:

# User Model
User:
  type: model
  mappings:
    id:
      type: string
      map: id
      required: true
    name:
      type: string
      map: fullName
    email:
      type: string
      required: true
    address:
      type: string
      map: address.street
  relationships:
    posts:
      type: Post[]
      map: user.posts

# Post Model
Post:
  type: model
  mappings:
    id:
      type: string
      required: true
    title:
      type: string
    content:
      type: string
      map: body
  relationships:
    author:
      type: User
      map: post.user

2. Form Validation Schema

Create a form.tw file for API validation rules:

User:
  create:
    fullName:
      required: true
      min: 2
      max: 100
      messages:
        required: "Full name is required"
        min: "Name must be at least {min} characters"
    
    email:
      required: true
      email: true
      messages:
        email: "Please enter a valid email address"

    # Array validation example
    addresses:
      type: array
      item:
        type: object
        properties:
          street:
            required: true
            min: 5
          city:
            required: true
      max_items: 3
      messages:
        max_items: "Maximum {max} addresses allowed"

  update:
    id:
      required: true
    fullName:
      min: 2
      max: 100
    email:
      email: true

3. Generated Structure

After running the generators, your directory will look like:

mappers/
├── schema.tw                 # Model schema definition
├── form.tw                  # Form validation schema
├── user/                    
│   ├── user.model.ts       # User Plain Model
│   ├── user.dto.ts         # User DTO with mapping
│   └── forms/              # Generated form validators
│       ├── create-user.form.ts
│       ├── update-user.form.ts
│       └── delete-user.form.ts
└── post/                    
    ├── post.model.ts       
    ├── post.dto.ts         
    └── forms/           

4. CLI Commands

Generate Models & DTOs

# Initialize schema
npx tw mapper init

# Generate all models
npx tw mapper generate

# Generate specific models
npx tw mapper generate -m user,post

# Watch mode
npx tw mapper generate -w

Options:

Option Description Default
-m, --models Models to generate All models
-w, --watch Watch for changes false
-f, --fix Auto-fix ESLint false
-s, --schema Schema file path ./mappers/schema.tw

Generate Form Validators

# Initialize form schema
npx tw form init

# Generate all form validators
npx tw form generate

# Generate for specific models
npx tw form generate -m user,post

# Watch mode
npx tw form generate -w

# Custom i18n import path
npx tw form generate -i '@/locales/i18n'

Options:

Option Description Default
-m, --models Models to generate All models
-w, --watch Watch for changes false
-f, --fix Auto-fix ESLint false
-s, --schema Schema file path ./mappers/form.tw
-i, --i18nPath Custom i18n import path @/utils/i18n

Generate Services

# Initialize service infrastructure
npx tw service init

# Generate services
npx tw service create -n user,post

Options:

Option Description Default
-n, --name Services to generate Required
-o, --output Output directory ./services

5. Validation Rules Reference

String Validations

  • required: boolean
  • min: number (min length)
  • max: number (max length)
  • email: boolean
  • regex: string
  • url: boolean
  • uuid: boolean
  • cuid: boolean
  • length: number
  • startsWith: string
  • endsWith: string
  • includes: string

Number Validations

  • type: number
  • gt: number (greater than)
  • gte: number (greater than or equal)
  • lt: number (less than)
  • lte: number (less than or equal)
  • int: boolean
  • positive: boolean
  • negative: boolean
  • multipleOf: number
  • finite: boolean
  • safe: boolean

Array Validations

  • type: array
  • nonempty: boolean
  • min_items: number
  • max_items: number
  • item: object (nested validation)

Object Validations

  • type: object
  • properties: Record<string, ValidationRule>

Custom Messages

fieldName:
  required: true
  min: 2
  messages:
    required: "Custom required message"
    min: "Must be at least {min} chars"

i18n Support

fieldName:
  required: true
  i18n:
    required: "validation.field.required"

6. Using Services

// Auto-imported service
const userService = useUserService()

// Create with form validation
const { data: newUser } = await userService.create({
  fullName: 'John Doe',
  email: 'john@example.com'
} satisfies CreateUserForm) // Type-safe form validation

// Update with form validation
const { data: updated } = await userService.update('1', {
  fullName: 'John Smith'
} satisfies UpdateUserForm)

// With custom options and form validation
const { data } = await userService.all({
  query: { role: 'admin' } satisfies GetUsersForm
})

// Error handling with Zod validation
try {
  const { data } = await userService.create({
    // Invalid data
    email: 'invalid-email'
  } satisfies CreateUserForm)
} catch (error) {
  if (error instanceof z.ZodError) {
    // Type-safe validation errors
    console.log(error.errors)
  }
}

Contributing

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Development
npm run dev

# Build
npm run dev:build

# Run ESLint
npm run lint

# Run Tests
npm run test
npm run test:watch

# Release
npm run release

License

MIT License

Package Sidebar

Install

npm i @tamnt-work/nuxt-mapper

Weekly Downloads

7

Version

1.4.4

License

MIT

Unpacked Size

432 kB

Total Files

15

Last publish

Collaborators

  • tamnt1707