@siyavuyachagi/typesharp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Siyavuya Chagi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,389 @@
+# TypeSharp
+
+Generate TypeScript types from C# models with ease! TypeSharp scans your ASP.NET Core projects and automatically generates TypeScript interfaces from your C# classes decorated with the `[TypeSharp]` attribute.
+
+## Features
+
+✨ **Automatic Type Generation** – Convert C# models to TypeScript interfaces  
+🎯 **Custom Attribute Targeting** – Use `[TypeSharp]` or any custom attribute  
+🔄 **Nullable Support** – `string?` → `string | null`  
+📦 **Collection Handling** – Supports `List<T>`, `IEnumerable<T>`, arrays **and generic collections**  
+🧬 **Generic Types** – Preserves generic type definitions like `Response<T>` → `Response<T>`  
+🧬 **Inheritance** – Preserves class inheritance using `extends`  
+🎨 **Naming Conventions** – Convert property names (camel, pascal, snake, kebab)  
+📁 **Flexible Output** – Single file or multiple files  
+🔢 **Enum Support** – Converts C# enums to TypeScript string enums  
+🗂️ **File Grouping** – Preserves C# file organization (multiple classes per file stay together)
+
+
+## How TypeSharp Compares   
+This is not an OpenApi-based tool !
+| Feature               | TypeSharp | NSwag | openapi-typescript | TypeGen |
+| --------------------- | --------- | ----- | ------------------ | ------- |
+| Direct C# parsing     | ✅         | ❌     | ❌                  | ✅       |
+| Attribute targeting   | ✅         | ⚠️    | ❌                  | ⚠️      |
+| Non-API models        | ✅         | ❌     | ❌                  | ✅       |
+| Generics preserved    | ✅         | ⚠️    | ⚠️                 | ⚠️      |
+| File grouping         | ✅         | ❌     | ❌                  | ❌       |
+| Naming control        | ✅         | ⚠️    | ⚠️                 | ❌       |
+| API client generation | ❌         | ✅     | ❌                  | ❌       |
+
+For more [docs/why-typesharp](docs/why-typesharp.md)
+
+
+## Installation
+
+```bash
+npm install -D @siyavuyachagi/typesharp
+```
+
+## Quick Start
+
+### 1. Create an attribute to target
+
+In your target project create the following attribute (`TypeSharp`)
+
+```cs
+namespace YourProject.Attribute
+{
+  [AttributeUsage(AttributeTargets.Class | AttributeTargets.Enum)]
+  public class TypeSharpAttribute : Attribute { }
+}
+```
+
+### 2. Decorate your C# models or DTOs
+
+```csharp
+[TypeSharp]
+public class User
+{
+  public int Id { get; set; }
+  public string? Name { get; set; }
+  public string Email { get; set; }
+  public List<UserRole> Roles { get; set; }
+  public List<string> Permissions { get; set; }
+  public DateTime CreatedAt { get; set; }
+}
+
+[TypeSharp]
+public enum UserRole
+{
+  Admin,
+  User,
+  Guest
+}
+
+[TypeSharp]
+public class ApiResponse<T>
+{
+  public bool Success { get; set; }
+  public string? Message { get; set; }
+  public T Data { get; set; }
+  public List<string> Errors { get; set; }
+}
+```
+
+### 3. Create a configuration file
+
+In your frontend end project run the following script
+
+```bash
+# Create TypeScript config
+npx typesharp init
+
+# ----- OR -------
+
+# Create JSON config (default)
+npx typesharp init --format json
+
+# Create TypeScript config
+npx typesharp init --format ts
+
+# Create JavaScript config
+npx typesharp init --format js
+
+```
+
+This creates `typesharp.config.json`:
+
+```json
+{
+  "projectFile": [
+    "C:/Users/User/Desktop/MyApp/Api/Api.csproj",
+    "C:/Users/User/Desktop/MyApp/Domain/Domain.csproj"
+  ],
+  "outputPath": "./app/types",
+  "targetAnnotation": "TypeSharp",
+  "singleOutputFile": false,
+  "fileNamingConvention": "kebab",
+  "namingConvention": "camel"
+}
+```
+
+### 4. Generate TypeScript types
+
+```bash
+npx typesharp
+
+# ----- OR -------
+
+npx typesharp generate
+# or with custom config
+npx typesharp generate --config ./custom-config.ts
+```
+
+Output (`app/types/user.ts`):
+
+```typescript
+/**
+ * Auto-generated by TypeSharp
+ * Generated at: 2024-12-12T10:30:00.000Z
+ * Do not edit this file manually
+ */
+
+export interface User {
+  id: number;
+  name: string | null;
+  email: string;
+  roles: UserRole[];
+  permissions: string[];
+  createdAt: string;
+}
+```
+
+Output (`app/types/user-role.ts`):
+
+```ts
+/**
+ * Auto-generated by TypeSharp
+ * Generated at: 2024-12-12T10:30:00.000Z
+ * Do not edit this file manually
+ */
+
+export enum UserRole {
+  Admin = "Admin",
+  User = "User",
+  Guest = "Guest",
+}
+```
+
+Output (`app/types/api-response.ts`):
+
+```ts
+/**
+ * Auto-generated by TypeSharp
+ * Generated at: 2024-12-12T10:30:00.000Z
+ * Do not edit this file manually
+ */
+
+export interface ApiResponse<T> {
+  success: boolean;
+  message: string | null;
+  data: T;
+  errors: string[];
+}
+```
+For more advanced usage [docs/usage](docs/usage.md)
+
+## Configuration
+
+### 1. Configuration Options
+
+| Option                 | Type       | Default       | Description                                      |
+| ---------------------- | ---------- | ------------- | ------------------------------------------------ |
+| `projectFiles`         | `string[]` | _required_    | Full path(s) to your C# .csproj file             |
+| `outputPath`           | `string`   | _required_    | Where to generate TypeScript files               |
+| `targetAnnotation`     | `string`   | `'TypeSharp'` | C# attribute name to look for                    |
+| `singleOutputFile`     | `boolean`  | `false`       | Generate one file or multiple files (see below)  |
+| `fileNamingConvention` | `string`   | `'kebab'`     | File naming: `kebab`, `camel`, `pascal`, `snake` |
+| `namingConvention`     | `string`   | `'camel'`     | Property naming: `camel`, `pascal`, `snake`      |
+| `fileSuffix`           | `string`   | `optional`    | Suffix for file names: `user-dto.ts`             |
+
+### 2. Output File Behavior
+
+TypeSharp preserves your C# file organization. Here's how it works:
+
+| C# File Structure                                          | `singleOutputFile: false`                        | `singleOutputFile: true`  |
+| ---------------------------------------------------------- | ------------------------------------------------ | ------------------------- |
+| **One class per file**<br>`User.cs` → 1 class              | `user.ts` (1 interface)                          | All classes in `types.ts` |
+| **Multiple classes per file**<br>`UserDtos.cs` → 3 classes | `user-dtos.ts` (3 interfaces)                    | All classes in `types.ts` |
+| **Mixed structure**<br>Various C# files                    | Each C# file → 1 TS file<br>(preserves grouping) | All classes in `types.ts` |
+
+**Example:**
+
+```
+C# Structure:                       TypeScript Output (singleOutputFile: false):
+Backend/                           src/types/
+├── DTOs/                         └── DTOs/
+│   ├── UserDtos.cs               │   ├── user-dtos.ts      ← All 3 classes together
+│   │   ├── UserCreateDto         │   └── product-dtos.ts   ← All 2 classes together
+│   │   ├── UserUpdateDto
+│   │   └── UserResponseDto
+│   └── ProductDtos.cs
+│       ├── ProductDto
+│       └── ProductCreateDto
+```
+
+**This means if you organize related DTOs in one C# file, they'll stay together in the generated TypeScript file!** 🎯
+
+### 3. Configuration File Formats
+
+TypeSharp supports multiple configuration formats:
+
+**JSON** (`typesharp.config.json`): (recommended)
+
+```json
+{
+  "projectFiles": ["C:/Users/User/Desktop/MyApp/Domain/Domain.csproj"],
+  "outputPath": "./src/types"
+}
+```
+
+**TypeScript** (`typesharp.config.ts`):
+
+```typescript
+import { TypeSharpConfig } from "typesharp";
+
+const config: TypeSharpConfig = {
+  projectFiles: ["C:/Users/User/Desktop/MyApp/Domain/Domain.csproj"],
+  outputPath: "./src/types",
+};
+
+export default config;
+```
+
+**JavaScript** (`typesharp.config.js`):
+
+```javascript
+module.exports = {
+  projectFiles: ["C:/Users/User/Desktop/MyApp/Domain/Domain.csproj"],
+  outputPath: "./src/types",
+};
+```
+
+## Usage in package.json
+
+Add TypeSharp to your build scripts:
+
+```json
+{
+  "scripts": {
+    "generate-types": "typesharp",
+    "dev": "typesharp && nuxt dev",
+    "build": "typesharp && nuxt build"
+  }
+}
+```
+
+## Advanced Examples
+
+### 1. With Inheritance
+
+**C#:**
+
+```csharp
+[TypeSharp]
+public class BaseEntity
+{
+    public int Id { get; set; }
+    public DateTime CreatedAt { get; set; }
+}
+
+[TypeSharp]
+public class Product : BaseEntity
+{
+    public string Name { get; set; }
+    public decimal Price { get; set; }
+}
+```
+
+**Generated TypeScript:**
+
+```typescript
+export interface BaseEntity {
+  id: number;
+  createdAt: string;
+}
+
+export interface Product extends BaseEntity {
+  name: string;
+  price: number;
+}
+```
+
+### 2. Single Output File
+
+**Config:**
+
+```typescript
+const config: TypeSharpConfig = {
+  projectFile: "./Backend/Backend.csproj",
+  outputPath: "./src/types",
+  singleOutputFile: true,
+};
+```
+
+All types will be generated in `src/types/index.ts`
+
+### 3. Custom Naming Conventions
+
+**Config:**
+
+```typescript
+const config: TypeSharpConfig = {
+  projectFile: "./Backend/Backend.csproj",
+  outputPath: "./src/types",
+  fileNamingConvention: "snake", // user_model.ts
+  namingConvention: "pascal", // UserName, not userName
+};
+```
+
+## Type Mappings
+
+| C# Type                                     | TypeScript Type  |
+| ------------------------------------------- | ---------------- |
+| `string`                                    | `string`         |
+| `int`, `long`, `double`, `float`, `decimal` | `number`         |
+| `bool`                                      | `boolean`        |
+| `DateTime`, `DateOnly`, `TimeOnly`          | `string`         |
+| `Guid`                                      | `string`         |
+| `List<T>`, `IEnumerable<T>`, `T[]`          | `T[]`            |
+| `string?`                                   | `string \| null` |
+
+## Programmatic Usage
+
+You can also use TypeSharp programmatically:
+
+```typescript
+import { generate } from "typesharp";
+
+async function generateTypes() {
+  await generate("./path/to/config.ts");
+}
+
+generateTypes();
+```
+
+## Requirements
+
+- Node.js >= 14
+- TypeScript >= 4.5 (if using TypeScript config)
+
+<!-- ## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. -->
+
+## License
+
+MIT © Siyavuya Chagi
+
+## Author
+
+**Siyavuya Chagi (CeeJay)**
+
+- GitHub: [@siyavuyachagi](https://github.com/siyavuyachagi)
+- Email: syavuya08@gmail.com
+
+---
+
+Built with ❤️ in South Africa 🇿🇦

package/bin/typesharp.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../dist/cli/index.js');

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}

package/dist/cli/index.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const core_1 = require("../core");
+const chalk_1 = __importDefault(require("chalk"));
+const program = new commander_1.Command();
+program
+    .name('typesharp')
+    .description('Generate TypeScript types from C# models with TypeSharp attribute')
+    .version('1.0.0')
+    .usage('[command] [options]');
+// Generate command (default)
+program
+    .command('generate', { isDefault: true })
+    .description('Generate TypeScript types from C# files')
+    .option('-c, --config <path>', 'Path to configuration file')
+    .action(async (options) => {
+    try {
+        await (0, core_1.generate)(options.config);
+        process.exit(0);
+    }
+    catch (error) {
+        process.exit(1);
+    }
+});
+// Init command
+program
+    .command('init')
+    .description('Create a sample configuration file')
+    .option('-f, --format <format>', 'Configuration file format (ts, js, json)', 'json') // default to 'json'
+    .action((options) => {
+    try {
+        const format = options.format;
+        if (!['ts', 'js', 'json'].includes(format)) {
+            console.error(chalk_1.default.red.bold('❌ Invalid format.') + ' Use: ' + chalk_1.default.yellow('json, ts, ') + 'or' + chalk_1.default.yellow(' js'));
+            process.exit(1);
+        }
+        (0, core_1.createSampleConfig)(format);
+        process.exit(0);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            console.error(chalk_1.default.red.bold(`❌ Error:`), chalk_1.default.white(error.message));
+        }
+        process.exit(1);
+    }
+});
+program.parse();
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";;;;;;AAEA,yCAAoC;AACpC,kCAAuD;AACvD,kDAA0B;AAE1B,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,WAAW,CAAC;KACjB,WAAW,CAAC,mEAAmE,CAAC;KAChF,OAAO,CAAC,OAAO,CAAC;KAChB,KAAK,CAAC,qBAAqB,CAAC,CAAC;AAEhC,6BAA6B;AAC7B,OAAO;KACJ,OAAO,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;KACxC,WAAW,CAAC,yCAAyC,CAAC;KACtD,MAAM,CAAC,qBAAqB,EAAE,4BAA4B,CAAC;KAC3D,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;IACxB,IAAI,CAAC;QACH,MAAM,IAAA,eAAQ,EAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC/B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,eAAe;AACf,OAAO;KACJ,OAAO,CAAC,MAAM,CAAC;KACf,WAAW,CAAC,oCAAoC,CAAC;KACjD,MAAM,CAAC,uBAAuB,EAAE,0CAA0C,EAAE,MAAM,CAAC,CAAC,oBAAoB;KACxG,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE;IAClB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,MAA8B,CAAC;QAEtD,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3C,OAAO,CAAC,KAAK,CAAC,eAAK,CAAC,GAAG,CAAC,IAAI,CAAC,mBAAmB,CAAC,GAAG,QAAQ,GAAG,eAAK,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,IAAI,GAAG,eAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACxH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,IAAA,yBAAkB,EAAC,MAAM,CAAC,CAAC;QAC3B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,OAAO,CAAC,KAAK,CAAC,eAAK,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,eAAK,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/core/index.d.ts

@@ -0,0 +1,16 @@
+import { TypeSharpConfig } from '../types/typesharp-config';
+export declare function generate(configPath?: string): Promise<void>;
+/**
+ * Deletes all contents of a directory but keeps the directory itself.
+ * @param dir Path to the directory to clean
+ */
+export declare function cleanOutputDirectory(dir: string): void;
+/**
+ * Load configuration from file or use provided config
+ */
+export declare function loadConfig(configPath?: string): TypeSharpConfig;
+/**
+ * Create a sample configuration file
+ */
+export declare function createSampleConfig(format?: 'ts' | 'js' | 'json'): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAuD5D,wBAAsB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiEjE;AASD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,QAiB/C;AAUD;;GAEG;AACH,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,eAAe,CAqB/D;AA2CD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,GAAE,IAAI,GAAG,IAAI,GAAG,MAAe,GAAG,IAAI,CAwC9E"}