adorn-api 1.0.25 → 1.0.27

package/README.md

@@ -21,6 +21,138 @@ Decorator-first web framework for TypeScript with OpenAPI 3.1 schema generation.
 npm install adorn-api express metal-orm
 ```
 
+## Project Setup
+
+Create a minimal `package.json` for your project:
+
+```json
+{
+  "name": "my-api",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "build": "tsc"
+  },
+  "dependencies": {
+    "adorn-api": "^1.0.25",
+    "express": "^4.19.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.5"
+  }
+}
+```
+
+**Dependencies explained:**
+- `adorn-api` - The main framework
+- `express` - HTTP server (required)
+- `tsx` - TypeScript execution for development
+- `typescript` - TypeScript compiler
+
+**Scripts explained:**
+- `npm run dev` - Run in development mode with hot reload
+- `npm run build` - Compile TypeScript to JavaScript
+- `npm start` - Run the compiled application
+
+## Getting Started
+
+Follow these steps to set up a new project from scratch:
+
+### 1. Create your project directory
+
+```bash
+mkdir my-api
+cd my-api
+```
+
+### 2. Initialize npm
+
+```bash
+npm init -y
+```
+
+### 3. Install dependencies
+
+```bash
+npm install adorn-api express
+npm install -D tsx typescript @types/node
+```
+
+### 4. Create `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "useDefineForClassFields": true,
+    "experimentalDecorators": false,
+    "emitDecoratorMetadata": false
+  },
+  "include": ["src"]
+}
+```
+
+### 5. Create `src/index.ts`
+
+```typescript
+import { Controller, Get, Dto, Field, t, createExpressApp } from "adorn-api";
+
+@Dto({ description: "User record" })
+class UserDto {
+  @Field(t.uuid({ description: "User ID" }))
+  id!: string;
+
+  @Field(t.string({ minLength: 1 }))
+  name!: string;
+}
+
+@Controller("/users")
+class UserController {
+  @Get("/:id")
+  @Params(UserDto)
+  @Returns(UserDto)
+  async getOne(ctx: RequestContext<unknown, undefined, UserDto>) {
+    return {
+      id: ctx.params.id,
+      name: "Ada Lovelace"
+    };
+  }
+}
+
+const app = createExpressApp({
+  controllers: [UserController],
+  openApi: {
+    info: { title: "My API", version: "1.0.0" },
+    docs: true
+  }
+});
+
+app.listen(3000, () => {
+  console.log("Server running at http://localhost:3000");
+  console.log("API docs at http://localhost:3000/docs");
+});
+```
+
+### 6. Run your application
+
+```bash
+npm run dev
+```
+
+Visit http://localhost:3000/docs to see your API documentation.
+
 ## Quick Start
 
 ```typescript
@@ -378,6 +510,55 @@ npm run lint
 npm run example basic
 ```
 
+## Common Pitfalls
+
+⚠️ **Important:** Adorn API uses standard ECMAScript decorators (Stage 3), NOT legacy TypeScript decorators.
+
+### ❌ DO NOT use these:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,   // ❌ WRONG - must be false
+    "emitDecoratorMetadata": true    // ❌ WRONG - must be false
+  }
+}
+```
+
+```bash
+npm install reflect-metadata  # ❌ WRONG - not needed
+tsx -r reflect-metadata src/index.ts  # ❌ WRONG - remove -r flag
+```
+
+### ✅ DO use these:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": false,  // ✅ CORRECT
+    "emitDecoratorMetadata": false   // ✅ CORRECT
+  }
+}
+```
+
+```bash
+tsx src/index.ts  # ✅ CORRECT - no reflect-metadata
+```
+
+### Why?
+
+- **Standard ECMAScript decorators** (Stage 3) are the modern, standardized approach
+- **Legacy TypeScript decorators** (`experimentalDecorators`) are deprecated
+- `reflect-metadata` is only needed for legacy decorators
+- TypeScript 5.0+ fully supports standard decorators
+
+### Troubleshooting
+
+If you see errors like:
+- `Decorators are not enabled` → Check `experimentalDecorators` is `false`
+- `Cannot find module 'reflect-metadata'` → Remove `reflect-metadata` from dependencies
+- `Decorator metadata not available` → This is expected with standard decorators
+
 ## TypeScript Configuration
 
 Ensure your `tsconfig.json` has:
@@ -385,15 +566,78 @@ Ensure your `tsconfig.json` has:
 ```json
 {
   "compilerOptions": {
-    "experimentalDecorators": false,
-    "emitDecoratorMetadata": false,
-    "useDefineForClassFields": true
-  }
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "useDefineForClassFields": true,
+    "experimentalDecorators": false,      // ⚠️ MUST be false
+    "emitDecoratorMetadata": false       // ⚠️ MUST be false
+  },
+  "include": ["src"]
 }
 ```
 
+**Critical settings:**
+- `experimentalDecorators: false` - Use standard ECMAScript decorators
+- `emitDecoratorMetadata: false` - Not needed with standard decorators
+- `useDefineForClassFields: true` - Required for standard decorators
+
 Adorn API uses standard ECMAScript decorators (Stage 3).
 
+## Quick Reference
+
+### Setup Checklist
+
+- [ ] Initialize project: `npm init -y`
+- [ ] Install dependencies: `npm install adorn-api express`
+- [ ] Install dev dependencies: `npm install -D tsx typescript @types/node`
+- [ ] Create `tsconfig.json` with correct decorator settings
+- [ ] Create `src/index.ts` with your controllers
+- [ ] Run: `npm run dev`
+
+### Common Commands
+
+```bash
+# Development
+npm run dev              # Run with hot reload
+npm run build            # Compile TypeScript
+npm start                # Run compiled app
+
+# Testing
+npm test                 # Run tests
+npm run test:watch       # Run tests in watch mode
+
+# Code Quality
+npm run lint             # Run ESLint
+```
+
+### Project Structure
+
+```
+my-api/
+├── src/
+│   └── index.ts         # Main entry point
+├── dist/                # Compiled JavaScript (generated)
+├── node_modules/
+├── package.json
+└── tsconfig.json
+```
+
+### Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Decorators not working | Check `experimentalDecorators: false` in tsconfig.json |
+| reflect-metadata errors | Remove `reflect-metadata` from package.json and scripts |
+| Module not found | Ensure `moduleResolution: "NodeNext"` in tsconfig.json |
+| Type errors | Run `npm run build` to see full TypeScript errors |
+
 ## License
 
 Check the package for license information.

package/dist/adapter/metal-orm/crud-dtos.js

@@ -83,7 +83,7 @@ function createMetalCrudDtoClasses(target, options = {}) {
     return classes;
 }
 function createNestedCreateDtoClass(target, overrides, options) {
-    const { additionalExclude, name, parentEntity, ...metalDtoOptions } = options;
+    const { additionalExclude, name, parentEntity: _parentEntity, ...metalDtoOptions } = options;
     const allExcludes = mergeStringArrays(["id", "createdAt"], additionalExclude, metalDtoOptions.exclude);
     let NestedCreateDto = (() => {
         let _classDecorators = [(0, dto_1.MetalDto)(target, {

package/dist/adapter/metal-orm/error-dtos.js

@@ -39,7 +39,7 @@ exports.createErrorDtoClass = createErrorDtoClass;
 const decorators_1 = require("../../core/decorators");
 const schema_1 = require("../../core/schema");
 function createErrorDtoClass(options = {}) {
-    const { withDetails = true, includeTraceId = true } = options;
+    const { withDetails = true, includeTraceId: _includeTraceId = true } = options;
     if (withDetails) {
         let ErrorDetailDto = (() => {
             let _classDecorators = [(0, decorators_1.Dto)()];

package/dist/core/metadata.js

@@ -12,6 +12,12 @@ const dtoStore = new Map();
 const controllerStore = new Map();
 exports.META_KEY = Symbol.for("adorn.metadata");
 function getAdornMetadata(metadata) {
+    // Handle case where metadata is undefined (when Symbol.metadata is not available)
+    if (!metadata) {
+        const temp = {};
+        temp[exports.META_KEY] = {};
+        return temp[exports.META_KEY];
+    }
     if (!metadata[exports.META_KEY]) {
         metadata[exports.META_KEY] = {};
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adorn-api",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "description": "Decorator-first web framework with OpenAPI 3.1 schema generation.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/adapter/metal-orm/crud-dtos.ts

@@ -1,4 +1,4 @@
-import { Dto } from "../../core/decorators";
+
 import type { DtoConstructor } from "../../core/types";
 import { MetalDto } from "./dto";
 import type {
@@ -70,7 +70,7 @@ export function createNestedCreateDtoClass(
   overrides: Record<string, any>,
   options: NestedCreateDtoOptions
 ): DtoConstructor {
-  const { additionalExclude, name, parentEntity, ...metalDtoOptions } = options;
+  const { additionalExclude, name, parentEntity: _parentEntity, ...metalDtoOptions } = options;
 
   const allExcludes = mergeStringArrays(
     ["id", "createdAt"],

package/src/adapter/metal-orm/error-dtos.ts

@@ -4,7 +4,7 @@ import type { ErrorDtoOptions } from "./types";
 import { t } from "../../core/schema";
 
 export function createErrorDtoClass(options: ErrorDtoOptions = {}): DtoConstructor {
-  const { withDetails = true, includeTraceId = true } = options;
+  const { withDetails = true, includeTraceId: _includeTraceId = true } = options;
 
   if (withDetails) {
     @Dto()

package/src/adapter/metal-orm/filters.ts

@@ -1,4 +1,4 @@
-import type { Filter, FilterMapping, ParseFilterOptions } from "./types";
+import type { Filter } from "./types";
 
 /**
  * Parses filter parameters from query parameters.

package/src/adapter/metal-orm/paged-dtos.ts

@@ -1,6 +1,6 @@
 import { Dto, Field } from "../../core/decorators";
 import type { DtoConstructor } from "../../core/types";
-import type { SchemaNode } from "../../core/schema";
+
 import { t } from "../../core/schema";
 import type { FieldMeta } from "../../core/metadata";
 import { registerDto } from "../../core/metadata";

package/src/adapter/metal-orm/pagination.ts

@@ -1,4 +1,4 @@
-import type { PaginationConfig, PaginationOptions, ParsedPagination } from "./types";
+import type { PaginationConfig, ParsedPagination } from "./types";
 import { coerce } from "../../core/coerce";
 
 /**

package/src/adapter/metal-orm/types.ts

@@ -1,4 +1,4 @@
-import type { ColumnDef } from "metal-orm";
+
 import type { DtoOptions, FieldOverride } from "../../core/decorators";
 import type { SchemaNode } from "../../core/schema";
 import type { DtoConstructor } from "../../core/types";

package/src/core/metadata.ts

@@ -79,6 +79,13 @@ export interface RouteMetaInput extends Partial<RouteMeta> {
 }
 
 export function getAdornMetadata(metadata: DecoratorMetadata): AdornMetadata {
+  // Handle case where metadata is undefined (when Symbol.metadata is not available)
+  if (!metadata) {
+    const temp: any = {};
+    temp[META_KEY] = {};
+    return temp[META_KEY];
+  }
+  
   if (!metadata[META_KEY]) {
     metadata[META_KEY] = {};
   }

package/vitest.config.ts

@@ -1,8 +1,14 @@
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: {
-    environment: "node",
-    include: ["src/**/*.test.ts"]
-  }
-});
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+    pool: "forks",
+    poolOptions: {
+      forks: {
+        singleFork: true
+      }
+    }
+  }
+});