Archy

🚀 Developing an Archy Server with TypeScript

This guide provides a comprehensive walk - through on setting up and developing an Archy server using TypeScript, including installation, configuration, running, and troubleshooting.

📦 Installation

Installing Dependencies

To start developing Archy, first install the required dependencies:

npm install typescript ts-node nodemon @types/node @types/express --save-dev

Installing TypeScript

Install TypeScript and type definition files globally using the following command:

npm install -g typescript typescript@latest

📝 Writing Configuration Files

Create and edit the tsconfig.json file, adding the following content:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "esModuleInterop": true,
    "strict": true,
    "outDir": "build",
    "declaration": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "build"]
}

💻 Running in Development Mode

When running the server in a development environment, you can use the following command:

npm run dev

This command will automatically reload the server in response to file changes.

🔨 Compiling the TypeScript Project

Use the following methods to run the TypeScript compiler:

Using Locally Installed TypeScript

npx tsc

To specify the tsconfig.json file, execute:

npx tsc --project tsconfig.json

To enable watch mode (real - time recompilation), run:

npx tsc --watch

Using Globally Installed TypeScript

If you have installed TypeScript globally, execute the following command:

tsc

🛠️ Common TypeScript Compilation Options

• --outDir <directory>: Specify the output directory.
• --target <ES version>: Specify the ECMAScript target version (e.g., ES2020).
• --module <module system>: Specify the module system (e.g., NodeNext).
• --declaration: Generate .d.ts declaration files.
• --sourceMap: Generate source map files to support debugging.

📁 Project Structure

• src/: TypeScript source files
  • src/index.ts: Program entry point and server implementation
  • src/server.ts: Server implementation
  • src/generators/: Diagram generation logic
  • src/utils/: Utility functions and helper functions
• build/: Compiled JavaScript output files
• examples/: Example usage scripts
• test/: Test files

💻 Usage Examples

Example: Generating a Class Diagram from Text

generate_diagram_from_text({
  "description": "Create a class diagram for a library system that includes Book, Author, and Library classes. A book has a title and an ISBN. An author has a name and can write multiple books. The library collection contains books.",
  "language": "zh-CN"
});

Example: Generating a Diagram from a URL

generate_diagram_from_url({
  "url": "https://example.com",
  "language": "zh-CN"
});

⚙️ Configuring the Development Environment

Add the following content to the package.json file:

{
  "name": "archy-server",
  "version": "1.0.0",
  "scripts": {
    "dev": "ts-node src/index.ts"
  },
  "dependencies": {
    "express": "^4.18.2"
  },
  "devDependencies": {
    "typescript": "^5.0.2",
    "ts-node": "^10.9.2",
    "nodemon": "^3.0.2",
    "@types/node": "^20.10.0",
    "@types/express": "^4.18.1"
  }
}

🚀 Running the Server

Start the development server:

npm run dev

🛠️ Development Mode Features

Enabling Debug Logs

Add the following content to the tsconfig.json file to enable debug logs:

{
  "compilerOptions": {
    "traceResolution": true,
    "verbose": true
  }
}

🐞 Troubleshooting

Module Resolution Errors

Ensure that the tsconfig.json file exists in the project root directory and that the include and exclude configurations are correct.

Unable to Start the Server

Check if the installation was successful:

npm list -g typescript ts-node nodemon

💻 Code Examples

Simple HTTP Server

import express from 'express';

const app = express();
const port = 3000;

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(port, () => {
  console.log(`The application is running at http://localhost:${port}`);
});

Server with Routes

import express from 'express';
const router = express.Router();

router.get('/api', (req, res) => {
  res.json({ message: 'Hello API' });
});

const app = express();
app.use('/', router);

const port = 3000;
app.listen(port, () => {
  console.log(`The application is running at http://localhost:${port}`);
});

⚙️ Advanced Features

Configuring a Proxy

Edit the tsconfig.json file and add the following content:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

Then use the module path in the code:

import { generate_diagram_from_text } from '@';

Configuring TypeScript Module Resolution

Edit the tsconfig.json file and add the following content:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "baseUrl": "."
  }
}

📋 Summary

By following the steps above, you can successfully set up and develop an Archy server using TypeScript.