@trapi/metadata 1.3.0 → 2.0.0-beta.0

package/README.md

@@ -10,6 +10,10 @@ The metadata can than be used for generating a documentation according to the Op
 
 Inspect the `CHANGELOG.md` in the repository for breaking changes.
 
+## Public API
+
+The stable public surface is documented in the [API Reference](https://trapi.tada5hi.net/guide/metadata-api-reference). Anything not listed there should be treated as internal even if it is re-exported, and may change without a major version bump.
+
 **Table of Contents**
 
 - [Installation](#installation)
@@ -32,9 +36,10 @@ The metadata configuration object (Top-Level) is the main configuration object o
 and can be defined according the following type scheme:
 
 ```typescript
-import { 
+import type {
     CacheOptions,
-    DecoratorConfig 
+    DecoratorConfig,
+    TsConfig,
 } from "@trapi/metadata";
 
 export type EntryPointOptions = {
@@ -47,12 +52,12 @@ export type EntryPoint = string |
     EntryPointOptions |
     EntryPointOptions[];
 
-export interface Options {
+export interface MetadataGenerateOptions {
     /**
      * The entry point to your API.
      */
     entryPoint: EntryPoint;
-    
+
     /**
      * Directory to ignore during TypeScript files scan.
      * Default: []
@@ -64,13 +69,13 @@ export interface Options {
      * Default: []
      */
     allow?: string[],
-    
+
     /**
      * Directory to store and cache metadata files.
      * Default: false
      */
     cache?: string | boolean | Partial<CacheOptions>;
-    
+
     /**
      * Manual decorator properties configuration.
      */
@@ -80,18 +85,35 @@ export interface Options {
      * Load a specific preset configuration.
      */
     preset?: string;
+
+    /**
+     * Path to tsconfig.json or a TsConfig object.
+     */
+    tsconfig?: string | TsConfig;
 }
 ```
 
 ## Limitations
-At the moment only the following TypeScript UtilityTypes are supported:
-* NonNullable
-* Omit
-* Partial
-* Readonly
-* Record
-* Required
-* Pick
+
+TRAPI's resolver explicitly handles these TypeScript utility types:
+
+* `NonNullable`
+* `Omit`
+* `Partial`
+* `Readonly`
+* `Record`
+* `Required`
+* `Pick`
+
+Additionally these are delegated to the TypeScript type checker and resolve through the compiler's own computation:
+
+* `Extract`
+* `Exclude`
+* `ReturnType`
+* `Parameters`
+* `Awaited`
+* `InstanceType`
+* `ConstructorParameters`
 
 ## Usage
 
@@ -107,7 +129,7 @@ const metadata : Metadata = await generateMetadata({
     entryPoint: ['src/controllers/**/*.ts'],
     ignore: ['**/node_modules/**'],
     cache: true,
-    preset: '@trapi/preset-routup'
+    preset: '@trapi/preset-decorators-express'
 });
 
 console.log(metadata);
@@ -117,7 +139,32 @@ console.log(metadata);
 
 ## Structure
 
-**coming soon**
+The package follows a hexagonal layout:
+
+```
+src/
+├── core/         # Domain types, port interfaces, generator contracts
+│   ├── types/          # Metadata, Controller, Method, Parameter, Type, ...
+│   ├── config/         # MetadataGenerateOptions, MetadataGeneratorOptions, EntryPoint
+│   ├── decorator/      # DecoratorID enum, decorator config shapes
+│   ├── error/          # MetadataError, GeneratorError, ResolverError
+│   ├── metadata/       # IMetadataGenerator, IGeneratorContext
+│   └── utils/          # Internal helpers (hasOwnProperty, normalizePath, …)
+│
+├── adapters/     # Infrastructure adapters
+│   ├── typescript/     # TypeScript compiler API adapter (type resolver, JSDoc, AST)
+│   ├── decorator/      # Decorator resolver + preset loader
+│   ├── filesystem/     # Source file scanner, tsconfig loader
+│   └── cache/          # Metadata cache
+│
+├── app/          # Orchestration / use-cases
+│   ├── generate.ts     # generateMetadata()
+│   └── generator/      # Controller, Method, Parameter generators
+│
+└── index.ts      # Public entry point
+```
+
+The dependency rule is strict: `core/` imports nothing from `adapters/` or `app/`, `adapters/` depends only on `core/`, and `app/` wires both together.
 
 ## License