vite-plugin-ferry 0.1.2 → 0.1.4

package/README.md

@@ -10,10 +10,14 @@ in sync with your backend.
 - **Enums** — Generates types and runtime constants from `app/Enums/`
 - **Resources** — Generates response types from `app/Http/Resources/`
 
+## Requirements
+
+- **TypeScript ^5.0** — Required as a peer dependency for code generation
+
 ## Installation
 
 ```bash
-npm install vite-plugin-ferry --save-dev
+npm install vite-plugin-ferry typescript@^5 --save-dev
 ```
 
 Add it to your `vite.config.ts`:
@@ -33,9 +37,249 @@ Import your backend types directly in your frontend code:
 
 ```ts
 import { OrderStatus } from '@ferry/enums';
-import { UserResource } from '@ferry/resources';
+import type { UserResource } from '@ferry/resources';
+```
+
+## Examples
+
+### Enums
+
+#### String-backed enum with labels
+
+When your enum has a `label()` method, Ferry generates a typed constant object:
+
+```php
+// app/Enums/OrderStatus.php
+enum OrderStatus: string
+{
+    case Pending = 'pending';
+    case Shipped = 'shipped';
+    case Delivered = 'delivered';
+
+    public function label(): string
+    {
+        return match ($this) {
+            self::Pending => 'Pending Order',
+            self::Shipped => 'Shipped',
+            self::Delivered => 'Delivered',
+        };
+    }
+}
+```
+
+Generates:
+
+```ts
+// @ferry/enums
+export declare const OrderStatus: {
+  Pending: { value: 'pending'; label: 'Pending Order' };
+  Shipped: { value: 'shipped'; label: 'Shipped' };
+  Delivered: { value: 'delivered'; label: 'Delivered' };
+};
+```
+
+#### String-backed enum without labels
+
+Simple string enums become TypeScript enums:
+
+```php
+// app/Enums/Role.php
+enum Role: string
+{
+    case ADMIN = 'admin';
+    case USER = 'user';
+    case GUEST = 'guest';
+}
 ```
 
+Generates:
+
+```ts
+// @ferry/enums
+export enum Role {
+  ADMIN = 'admin',
+  USER = 'user',
+  GUEST = 'guest',
+}
+```
+
+#### Int-backed enum
+
+Integer enums work the same way:
+
+```php
+// app/Enums/Priority.php
+enum Priority: int
+{
+    case LOW = 1;
+    case MEDIUM = 2;
+    case HIGH = 3;
+    case URGENT = 4;
+}
+```
+
+Generates:
+
+```ts
+// @ferry/enums
+export enum Priority {
+  LOW = 1,
+  MEDIUM = 2,
+  HIGH = 3,
+  URGENT = 4,
+}
+```
+
+#### Unit enum (no backing type)
+
+Unit enums use their case names as values:
+
+```php
+// app/Enums/Color.php
+enum Color
+{
+    case RED;
+    case GREEN;
+    case BLUE;
+}
+```
+
+Generates:
+
+```ts
+// @ferry/enums
+export enum Color {
+  RED = 'RED',
+  GREEN = 'GREEN',
+  BLUE = 'BLUE',
+}
+```
+
+### Resources
+
+#### Basic resource
+
+```php
+// app/Http/Resources/UserResource.php
+class UserResource extends JsonResource
+{
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->resource->id,
+            'name' => $this->resource->name,
+            'email' => $this->resource->email,
+            'is_admin' => $this->resource->is_admin,
+            'created_at' => $this->resource->created_at,
+        ];
+    }
+}
+```
+
+Generates:
+
+```ts
+// @ferry/resources
+export type UserResource = {
+  id: string;
+  name: string;
+  email: string;
+  is_admin: boolean;
+  created_at: string;
+};
+```
+
+#### Resource with relations
+
+Fields using `whenLoaded()` become optional and resolve to the correct resource type:
+
+```php
+// app/Http/Resources/PostResource.php
+class PostResource extends JsonResource
+{
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->resource->id,
+            'title' => $this->resource->title,
+            'slug' => $this->resource->slug,
+            'is_published' => $this->resource->is_published,
+            'author' => UserResource::make($this->whenLoaded('author')),
+            'comments' => CommentResource::collection($this->whenLoaded('comments')),
+            'created_at' => $this->resource->created_at,
+        ];
+    }
+}
+```
+
+Generates:
+
+```ts
+// @ferry/resources
+export type PostResource = {
+  id: string;
+  title: string;
+  slug: string;
+  is_published: boolean;
+  author?: UserResource[];
+  comments?: CommentResource[];
+  created_at: string;
+};
+```
+
+#### Resource with nested objects
+
+Inline array structures become typed objects:
+
+```php
+// app/Http/Resources/OrderResource.php
+class OrderResource extends JsonResource
+{
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->resource->id,
+            'total' => $this->resource->total,
+            'status' => $this->resource->status,
+            'items' => $this->resource->items,
+            'user' => $this->whenLoaded('user'),
+            'shipping_address' => [
+                'street' => $this->resource->address_street,
+                'city' => $this->resource->address_city,
+                'zip' => $this->resource->address_zip,
+            ],
+            'created_at' => $this->resource->created_at,
+        ];
+    }
+}
+```
+
+Generates:
+
+```ts
+// @ferry/resources
+export type OrderResource = {
+  id: string;
+  total: string;
+  status: string;
+  items: string;
+  user?: UserResource;
+  shipping_address: { street: string; city: string; zip: string };
+  created_at: string;
+};
+```
+
+## Publishing
+
+To publish a new version:
+
+```bash
+npm version patch  # or minor, major
+git push --follow-tags
+```
+
+This bumps the version, creates a commit and tag, then pushes both to trigger the publish workflow.
+
 ## License
 
 See [LICENSE](LICENSE) for details.

package/dist/generators/enums.d.ts

@@ -3,6 +3,7 @@ export type EnumGeneratorOptions = {
     enumsDir: string;
     outputDir: string;
     packageName: string;
+    prettyPrint?: boolean;
 };
 /**
  * Generate TypeScript type declarations for enums.
@@ -11,9 +12,10 @@ export declare function generateEnumTypeScript(enums: Record<string, EnumDefinit
 /**
  * Generate runtime JavaScript for enums.
  */
-export declare function generateEnumRuntime(enums: Record<string, EnumDefinition>): string;
+export declare function generateEnumRuntime(enums: Record<string, EnumDefinition>, prettyPrint?: boolean): string;
 /**
  * Collect all enum definitions from the enums directory.
+ * This is a plugin-level function that handles file I/O.
  */
 export declare function collectEnums(enumsDir: string): Record<string, EnumDefinition>;
 /**

package/dist/generators/enums.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../src/generators/enums.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE5E,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,MAAM,CAyCpF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,MAAM,CAyBjF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAuB7E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CA6BjE"}
+{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../src/generators/enums.ts"],"names":[],"mappings":"AAIA,OAAO,EAAoB,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAc/E,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,MAAM,CA4BpF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,WAAW,UAAO,GAAG,MAAM,CAgCrG;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CA0B7E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CA6BjE"}

package/dist/generators/enums.js

@@ -1,81 +1,71 @@
+import ts from 'typescript';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { getPhpFiles, writeFileEnsureDir } from '../utils/file.js';
-import { parseEnumFile } from '../utils/php-parser.js';
+import { getPhpFiles, readFileSafe, writeFileEnsureDir } from '../utils/file.js';
+import { parseEnumContent } from '../utils/php-parser.js';
+import { printNodes, createEnum, createConstObject, createObjectLiteral, createDeclareConstWithType, createTypeLiteral, createStringLiteral, createNumericLiteral, createExportDefault, printNode, } from '../utils/ts-generator.js';
 /**
  * Generate TypeScript type declarations for enums.
  */
 export function generateEnumTypeScript(enums) {
-    const lines = [];
-    lines.push('// This file is auto-generated by the primcloud Vite plugin.');
-    lines.push('// Do not edit directly.');
-    lines.push('');
+    const nodes = [];
     for (const enumName of Object.keys(enums)) {
         const enumDef = enums[enumName];
         const hasLabels = enumDef.cases.some((c) => c.label);
         if (hasLabels) {
-            // Generate a const object with typed properties for enums with labels
-            lines.push(`export declare const ${enumDef.name}: {`);
-            for (const c of enumDef.cases) {
-                const val = String(c.value).replace(/'/g, "\\'");
-                const label = c.label ? String(c.label).replace(/'/g, "\\'") : val;
-                lines.push(`    ${c.key}: { value: '${val}'; label: '${label}' };`);
-            }
-            lines.push('};');
-            lines.push('');
+            // Generate a declare const with typed properties for enums with labels
+            const properties = enumDef.cases.map((c) => ({
+                name: c.key,
+                type: createTypeLiteral([
+                    { name: 'value', type: ts.factory.createLiteralTypeNode(createStringLiteral(String(c.value))) },
+                    {
+                        name: 'label',
+                        type: ts.factory.createLiteralTypeNode(createStringLiteral(c.label || String(c.value))),
+                    },
+                ]),
+            }));
+            nodes.push(createDeclareConstWithType(enumDef.name, createTypeLiteral(properties)));
         }
         else {
-            // Generate a traditional enum for enums without labels
-            lines.push(`export enum ${enumDef.name} {`);
-            for (const c of enumDef.cases) {
-                const val = c.value;
-                if (enumDef.backing === 'int' || enumDef.backing === 'integer') {
-                    if (!isNaN(Number(val))) {
-                        lines.push(`    ${c.key} = ${val},`);
-                    }
-                    else {
-                        lines.push(`    ${c.key} = '${val}',`);
-                    }
-                }
-                else {
-                    lines.push(`    ${c.key} = '${String(val).replace(/'/g, "\\'")}',`);
-                }
-            }
-            lines.push('}');
-            lines.push('');
+            // Generate a traditional enum
+            nodes.push(createEnum(enumDef.name, enumDef.cases.map((c) => ({ key: c.key, value: c.value }))));
         }
     }
-    return lines.join('\n');
+    return nodes.length > 0 ? printNodes(nodes) + '\n' : '';
 }
 /**
  * Generate runtime JavaScript for enums.
  */
-export function generateEnumRuntime(enums) {
-    const lines = [];
-    lines.push('// Auto-generated by primcloud Vite plugin');
-    lines.push('');
+export function generateEnumRuntime(enums, prettyPrint = true) {
+    const nodes = [];
     for (const enumName of Object.keys(enums)) {
         const enumDef = enums[enumName];
         const hasLabels = enumDef.cases.some((c) => c.label);
-        lines.push(`export const ${enumDef.name} = {`);
-        for (const c of enumDef.cases) {
-            const val = String(c.value).replace(/'/g, "\\'");
+        const properties = enumDef.cases.map((c) => {
+            let value;
             if (hasLabels) {
-                const label = c.label ? String(c.label).replace(/'/g, "\\'") : val;
-                lines.push(`  ${c.key}: { value: '${val}', label: '${label}' },`);
+                value = createObjectLiteral([
+                    { key: 'value', value: createStringLiteral(String(c.value)) },
+                    { key: 'label', value: createStringLiteral(c.label || String(c.value)) },
+                ], prettyPrint);
+            }
+            else if (typeof c.value === 'number') {
+                value = createNumericLiteral(c.value);
             }
             else {
-                lines.push(`  ${c.key}: '${val}',`);
+                value = createStringLiteral(String(c.value));
             }
-        }
-        lines.push('};');
-        lines.push('');
+            return { key: c.key, value };
+        });
+        nodes.push(createConstObject(enumDef.name, properties));
     }
-    lines.push('export default {};');
-    return lines.join('\n');
+    // Add export default {}
+    nodes.push(createExportDefault(ts.factory.createObjectLiteralExpression([])));
+    return nodes.map(printNode).join('\n\n') + '\n';
 }
 /**
  * Collect all enum definitions from the enums directory.
+ * This is a plugin-level function that handles file I/O.
  */
 export function collectEnums(enumsDir) {
     const enums = {};
@@ -86,7 +76,10 @@ export function collectEnums(enumsDir) {
     for (const file of enumFiles) {
         try {
             const enumPath = join(enumsDir, file);
-            const def = parseEnumFile(enumPath);
+            const content = readFileSafe(enumPath);
+            if (!content)
+                continue;
+            const def = parseEnumContent(content);
             if (def) {
                 enums[def.name] = def;
             }
@@ -102,7 +95,7 @@ export function collectEnums(enumsDir) {
  * Generate enum files (TypeScript declarations and runtime JavaScript).
  */
 export function generateEnums(options) {
-    const { enumsDir, outputDir, packageName } = options;
+    const { enumsDir, outputDir, packageName, prettyPrint = true } = options;
     // Collect all enums
     const enums = collectEnums(enumsDir);
     // Generate TypeScript declarations
@@ -110,7 +103,7 @@ export function generateEnums(options) {
     const dtsPath = join(outputDir, 'index.d.ts');
     writeFileEnsureDir(dtsPath, dtsContent);
     // Generate runtime JavaScript
-    const jsContent = generateEnumRuntime(enums);
+    const jsContent = generateEnumRuntime(enums, prettyPrint);
     const jsPath = join(outputDir, 'index.js');
     writeFileEnsureDir(jsPath, jsContent);
     // Generate package.json

package/dist/generators/resources.d.ts

@@ -1,18 +1,17 @@
+import { type ResourceFieldInfo } from '../utils/php-parser.js';
 export type ResourceGeneratorOptions = {
     resourcesDir: string;
     enumsDir: string;
     modelsDir: string;
     outputDir: string;
     packageName: string;
+    prettyPrint?: boolean;
 };
-type FieldInfo = {
-    type: string;
-    optional: boolean;
-};
+export type FieldInfo = ResourceFieldInfo;
 /**
  * Generate TypeScript type declarations for resources.
  */
-export declare function generateResourceTypeScript(resources: Record<string, Record<string, FieldInfo>>, fallbacks: string[], referencedEnums: Set<string>): string;
+export declare function generateResourceTypeScript(resources: Record<string, Record<string, ResourceFieldInfo>>, fallbacks: string[], referencedEnums: Set<string>): string;
 /**
  * Generate runtime JavaScript for resources.
  * Resources are type-only, so this just exports an empty object.
@@ -22,5 +21,4 @@ export declare function generateResourceRuntime(): string;
  * Generate resource type files (TypeScript declarations and runtime JavaScript).
  */
 export declare function generateResources(options: ResourceGeneratorOptions): void;
-export {};
 //# sourceMappingURL=resources.d.ts.map

package/dist/generators/resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../src/generators/resources.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,wBAAwB,GAAG;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,KAAK,SAAS,GAAG;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAiOF;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,EACpD,SAAS,EAAE,MAAM,EAAE,EACnB,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,GAC3B,MAAM,CAmCR;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAOhD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAqEzE"}
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../src/generators/resources.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,wBAAwB,CAAC;AAUhC,MAAM,MAAM,wBAAwB,GAAG;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAGF,MAAM,MAAM,SAAS,GAAG,iBAAiB,CAAC;AAE1C;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,EAC5D,SAAS,EAAE,MAAM,EAAE,EACnB,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,GAC3B,MAAM,CAuCR;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAoEzE"}