Skip to content

USAGE.md

Latest commit

 

History

History
133 lines (104 loc) · 3.4 KB

USAGE.md

File metadata and controls

133 lines (104 loc) · 3.4 KB

🎨 TypeORM Visual Usage Guide

TypeORM Visual is an interactive CLI tool that helps you create TypeORM entities for NestJS applications visually.

📥 Installation

Global installation (recommended)

npm install -g typeorm-visual

After installation, you can use the typeorm-visual command from anywhere.

Local installation

npm install typeorm-visual

When installed locally, you can use the tool with npx:

npx typeorm-visual <command>

🛠️ Commands

Interactive Entity Creator

The interactive entity creator guides you through the process of creating your database entities:

typeorm-visual create

This will:

  1. Prompt you to create one or more entities
  2. For each entity, you can define columns with their data types and constraints
  3. Define relationships between entities (one-to-one, one-to-many, many-to-one, many-to-many)
  4. Generate TypeORM entity files in the output/entities directory

Generate from JSON Schema

You can also generate entities from a JSON schema file:

typeorm-visual generate --file schema.json

The schema file should follow this format:

{
  "entities": [
    {
      "name": "User",
      "tableName": "users",
      "columns": [
        {
          "name": "id",
          "type": "uuid",
          "isPrimary": true,
          "isGenerated": true,
          "isNullable": false,
          "isUnique": true,
          "comment": "Primary key"
        },
        {
          "name": "username",
          "type": "varchar",
          "isPrimary": false,
          "isGenerated": false,
          "isNullable": false,
          "isUnique": true,
          "length": "100",
          "comment": "User's unique username"
        }
      ]
    }
  ],
  "relations": [
    {
      "sourceEntity": "Post",
      "targetEntity": "User",
      "relationType": "many-to-one",
      "sourceField": "author",
      "targetField": "posts",
      "isBidirectional": true,
      "joinColumn": "user_id",
      "isEager": false,
      "hasCascade": false
    }
  ]
}

See the blog-example.json for a complete example schema.

📃 Generated Code

The generated entity files are TypeORM entity classes ready to use in your NestJS application. They include:

  • 🏷️ Entity decorators with the correct table name
  • 📊 Column definitions with types, constraints, and comments
  • 🔗 Relationship decorators (OneToOne, OneToMany, ManyToOne, ManyToMany)
  • 🔄 Join column and join table decorators when needed

🧰 Supported Data Types

TypeORM Visual supports all common SQL data types:

  • 🔢 integer, bigint, smallint
  • 📊 float, double, decimal
  • ✅ boolean
  • 📝 varchar, char, text
  • 📅 date, datetime, timestamp, time
  • 🧩 enum, json, uuid

📋 Example Workflow

  1. Create a new NestJS project
  2. Install TypeORM Visual: npm install -g typeorm-visual
  3. Run the interactive creator: typeorm-visual create
  4. Define your entities and relationships
  5. Copy the generated entity files to your NestJS project's entity directory
  6. Use the entities in your NestJS modules and services

💡 Tips

  • Make sure to define sensible primary keys for your entities
  • When defining relationships, consider which side should be the owner of the relationship
  • For bidirectional relationships, pay attention to the inverse property names
  • Use cascade options carefully, especially for delete operations