@rexeus/typeweaver 0.8.0 → 0.9.0

package/README.md

@@ -68,20 +68,20 @@ More plugins are planned. If you want to build your own, check out the plugin sy
 
 ## ⌨️ CLI
 
-Generate TypeScript code from your API definitions:
+Generate TypeScript code from a spec entrypoint file:
 
 ```bash
 # Node.js (npm)
-npx typeweaver generate --input ./api/definition --output ./api/generated --plugins clients
+npx typeweaver generate --input ./api/spec/index.ts --output ./api/generated --plugins clients
 
 # Node.js (pnpm)
-pnpx typeweaver generate --input ./api/definition --output ./api/generated --plugins clients
+pnpx typeweaver generate --input ./api/spec/index.ts --output ./api/generated --plugins clients
 
 # Deno
-deno run -A npm:@rexeus/typeweaver generate --input ./api/definition --output ./api/generated --plugins clients
+deno run -A npm:@rexeus/typeweaver generate --input ./api/spec/index.ts --output ./api/generated --plugins clients
 
 # Bun
-bunx typeweaver generate --input ./api/definition --output ./api/generated --plugins clients
+bunx typeweaver generate --input ./api/spec/index.ts --output ./api/generated --plugins clients
 ```
 
 > **Note**: Deno may require the `--sloppy-imports` flag or equivalent configuration in `deno.json`
@@ -89,10 +89,8 @@ bunx typeweaver generate --input ./api/definition --output ./api/generated --plu
 
 ### ⚙️ Options
 
-- `--input, -i <path>`: Input directory containing API definitions (required)
+- `--input, -i <path>`: Spec entrypoint file (required)
 - `--output, -o <path>`: Output directory for generated code (required)
-- `-s, --shared <path>`: Shared directory for reusable schemas (optional, defaults to
-  `<input-path>/shared`)
 - `--config, -c <path>`: Configuration file path (optional)
 - `--plugins, -p <plugins>`: Comma-separated list of plugins to use (e.g., "clients,hono" or "all"
   for all plugins)
@@ -105,7 +103,7 @@ Create a config file (e.g. `typeweaver.config.js`) for more complex configuratio
 
 ```javascript
 export default {
-  input: "./api/definition",
+  input: "./api/spec/index.ts",
   output: "./api/generated",
   plugins: ["clients", "hono", "aws-cdk"],
   format: true,
@@ -126,222 +124,103 @@ npx typeweaver generate --config ./typeweaver.config.js
 
 ### 📁 Project Structure
 
-Your API definition must follow this structure:
-
-- Each resource needs its own directory under the specified input directory (e.g. input dir:
-  `api/definition` contains `user/`, `post/` subdirectories)
-  - The directory name defines the resource name (e.g. `user`, `post`)
-  - The structure inside a resource directory can be nested to provide better organization (e.g.
-    `user/errors/...`, `user/mutations/...`)
-- Inside a resource directory, each operation or response definition gets its own file (e.g.
-  `CreateUserDefinition.ts`, `UserNotFoundErrorDefinition.ts`)
-- An operation definition file must include one default export of a `HttpOperationDefinition`
-  instance (e.g. `export default new HttpOperationDefinition({...})`)
-- It is recommended to specify separate schemas for requests and responses, but this is not strictly
-  required.
-  - If separating schemas, Zod utilities can be used to apply general schemas case-specifically
-    (useful Zod utilities: pick, omit, merge...)
-- A response definition file must include one default export of a `HttpResponseDefinition` instance
-  (e.g. `export default new HttpResponseDefinition({...})`)
-- Responses shared across operations are possible, but need to be placed in the `shared` directory.
-  - The shared directory can be specified using the `--shared` option, but must be located within
-    the input directory
-  - Default shared directory is `<input-path>/shared`
-  - The shared directory is suitable not only as a place for responses but also for shared schemas
-
-As you can see, the structure of the input directory is essential. However, you are completely free
-to choose the structure and nesting within resource directories.
-
-**Important**: All definition files and their dependencies (like separate schemas etc.) must be
-self-contained within the input directory. Generated code creates an immutable snapshot of your
-definitions, so any external imports (relative imports outside the input directory) will not work.
-NPM package imports continue to work normally.
-
-```
-api/definition/
-├── user/                                  # Resource directory
-│   ├── errors/                            # Resource-specific error definitions
-│   │   │                                  # -> Because they are inside a resource directory,
-│   │   │                                  # they can only be used within this resource
-│   │   └── UserNotFoundErrorDefinition.ts
-│   │   └── UserStatusTransitionInvalidErrorDefinition.ts
-│   ├── CreateUserDefinition.ts            # Operation definitions
-│   ├── GetUserDefinition.ts
-│   ├── ListUserDefinition.ts
-│   ├── UpdateUserDefinition.ts
-│   └── userSchema.ts                      # Schema for the resource, can be reused across operations
-├── post/
-│   ├── errors/
-│   ├── CreatePostDefinition.ts
-│   ├── GetPostDefinition.ts
-│   ├── ...
-├── ...
-└── shared/                                # Shared responses and schemas
-   │                                       # -> While it doesn't matter where schemas are defined
-   │                                       # inside the input directory, responses can only be
-   │                                       # shared across resources if they are located in the
-   │                                       # shared directory
-   ├── ConflictErrorDefinition.ts
-   ├── ForbiddenErrorDefinition.ts
-   ├── InternalServerErrorDefinition.ts
-   ├── NotFoundErrorDefinition.ts          # Like BaseApiErrors, can be extended to be resource-specific
-   ├── TooManyRequestsErrorDefinition.ts
-   ├── UnauthorizedErrorDefinition.ts
-   ├── ValidationErrorDefinition.ts
-   └── sharedResponses.ts                  # Collection of responses relevant for every operation
+Typeweaver reads a single spec entrypoint. Organize files however you want, then assemble the
+resource map in `defineSpec(...)`. Here is an example layout:
+
+```text
+api/spec/
+├── index.ts                              # Spec entrypoint — exports defineSpec(...)
+├── user/
+│   ├── index.ts                          # Barrel exports for the user resource
+│   ├── userSchema.ts                     # Zod schemas for the user entity
+│   ├── GetUserDefinition.ts              # defineOperation(...) for GET /users/:userId
+│   └── errors/
+│       └── UserNotFoundErrorDefinition.ts
+└── shared/
+    ├── sharedResponses.ts                # Array of common error responses
+    └── ValidationErrorDefinition.ts
 ```
 
-### 💻 Sample Definitions
+This is just one way to organize your spec. The directory layout is up to you — typeweaver only
+cares about the `defineSpec(...)` entrypoint, not about folder names or file conventions.
 
-```typescript
-// api/definition/user/userSchema.ts
-import { z } from "zod";
+- Resource names come from `defineSpec({ resources: ... })`, not from directory names.
+- Shared responses and schemas can live anywhere that your spec entrypoint imports from.
+- The CLI bundles the entrypoint, so local spec imports should stay within your project.
 
-// General schema for user status
-export const userStatusSchema = z.enum(["ACTIVE", "INACTIVE", "SUSPENDED"]);
-
-// General user schema, can be reused across operations
-export const userSchema = z.object({
-  id: z.uuid(),
-  name: z.string(),
-  email: z.email(),
-  status: userStatusSchema,
-  createdAt: z.iso.date(),
-  updatedAt: z.iso.date(),
-});
-```
+### 💻 Sample Spec
 
 ```typescript
-// api/definition/user/GetUserDefinition.ts
-import { HttpOperationDefinition, HttpMethod, HttpStatusCode } from "@rexeus/typeweaver-core";
+// api/spec/user/GetUserDefinition.ts
+import {
+  defineOperation,
+  defineResponse,
+  HttpMethod,
+  HttpStatusCode,
+} from "@rexeus/typeweaver-core";
 import { z } from "zod";
 import { sharedResponses } from "../shared/sharedResponses";
 import { userSchema } from "./userSchema";
 import UserNotFoundErrorDefinition from "./errors/UserNotFoundErrorDefinition";
 
-export default new HttpOperationDefinition({
+export default defineOperation({
   operationId: "GetUser",
   method: HttpMethod.GET,
   path: "/users/:userId",
+  summary: "Get a user by id",
   request: {
     param: z.object({
       userId: z.uuid(),
     }),
   },
   responses: [
-    // - the only success response in this operation is defined inline
-    // - the response could also be defined in a separate file and be imported here
-    // - generally also multiple success responses could be defined
-    // - in this case the "general" user schema is imported and used
-    {
+    defineResponse({
+      name: "GetUserSuccess",
       statusCode: HttpStatusCode.OK,
       description: "User successfully retrieved",
       header: z.object({
         "Content-Type": z.literal("application/json"),
       }),
       body: userSchema,
-    },
-    UserNotFoundErrorDefinition, // Resource specific response
-    ...sharedResponses, // Commonly used responses across all operations, e.g. 401, 403, 500...
+    }),
+    UserNotFoundErrorDefinition,
+    ...sharedResponses,
   ],
 });
 ```
 
 ```typescript
-// api/definition/user/UpdateUserDefinition.ts
-import { HttpOperationDefinition, HttpMethod, HttpStatusCode } from "@rexeus/typeweaver-core";
-import { z } from "zod";
-import { sharedResponses } from "../shared/sharedResponses";
-import { userSchema } from "./userSchema";
-import UserNotFoundErrorDefinition from "./errors/UserNotFoundErrorDefinition";
-import UserStatusTransitionInvalidErrorDefinition from "./errors/UserStatusTransitionInvalidErrorDefinition";
-
-export default new HttpOperationDefinition({
-  operationId: "UpdateUser",
-  method: HttpMethod.PATCH,
-  path: "/users/:userId",
-  request: {
-    param: z.object({
-      userId: z.uuid(),
-    }),
-    // general user schema is processed via zod's pick and partial methods
-    // to match the update operation's requirements
-    body: userSchema
-      .pick({
-        name: true,
-        email: true,
-        status: true,
-      })
-      .partial(),
-  },
-  responses: [
-    {
-      statusCode: HttpStatusCode.OK,
-      description: "User successfully updated",
-      header: z.object({
-        "Content-Type": z.literal("application/json"),
-      }),
-      body: userSchema,
+// api/spec/index.ts
+import { defineSpec } from "@rexeus/typeweaver-core";
+import GetUserDefinition from "./user/GetUserDefinition";
+
+export default defineSpec({
+  resources: {
+    user: {
+      operations: [GetUserDefinition],
     },
-    UserNotFoundErrorDefinition, // Resource specific response
-    UserStatusTransitionInvalidErrorDefinition, // Resource specific response
-    ...sharedResponses, // Commonly used responses across all operations, e.g. 401, 403, 500...
-  ],
+  },
 });
 ```
 
 ```typescript
-// api/definition/user/errors/UserNotFoundErrorDefinition.ts
+// api/spec/user/userSchema.ts
 import { z } from "zod";
-import { NotFoundErrorDefinition } from "../../shared";
-
-// - uses the shared NotFoundErrorDefinition as "base" and extends it
-// - adds a specific message and code for the user resource
-export default NotFoundErrorDefinition.extend({
-  name: "UserNotFoundError",
-  description: "User not found",
-  body: z.object({
-    message: z.literal("User not found"),
-    code: z.literal("USER_NOT_FOUND_ERROR"),
-    actualValues: z.object({
-      userId: z.uuid(),
-    }),
-  }),
-});
-```
 
-```typescript
-// api/definition/user/errors/UserStatusTransitionInvalidErrorDefinition.ts
-import { HttpResponseDefinition, HttpStatusCode } from "@rexeus/typeweaver-core";
-import { z } from "zod";
-import { userStatusSchema } from "../userSchema";
-
-// could also extend the shared ConflictErrorDefinition:
-// export default ConflictErrorDefinition.extend({...});
-
-// or in this case does not extend a BaseApiError and defines everything itself
-export default new HttpResponseDefinition({
-  name: "UserStatusTransitionInvalidError",
-  description: "User status transition is conflicting with current status",
-  body: z.object({
-    message: z.literal("User status transition is conflicting with current status"),
-    code: z.literal("USER_STATUS_TRANSITION_INVALID_ERROR"),
-    context: z.object({
-      userId: z.uuid(),
-      currentStatus: userStatusSchema,
-    }),
-    actualValues: z.object({
-      requestedStatus: userStatusSchema,
-    }),
-    expectedValues: z.object({
-      allowedStatuses: z.array(userStatusSchema),
-    }),
-  }),
+export const userStatusSchema = z.enum(["ACTIVE", "INACTIVE", "SUSPENDED"]);
+
+export const userSchema = z.object({
+  id: z.uuid(),
+  name: z.string(),
+  email: z.email(),
+  status: userStatusSchema,
+  createdAt: z.iso.date(),
+  updatedAt: z.iso.date(),
 });
 ```
 
 ```typescript
-// api/definition/shared/sharedResponses.ts
+// api/spec/shared/sharedResponses.ts
 import ForbiddenErrorDefinition from "./ForbiddenErrorDefinition";
 import InternalServerErrorDefinition from "./InternalServerErrorDefinition";
 import TooManyRequestsErrorDefinition from "./TooManyRequestsErrorDefinition";
@@ -349,8 +228,6 @@ import UnauthorizedErrorDefinition from "./UnauthorizedErrorDefinition";
 import UnsupportedMediaTypeErrorDefinition from "./UnsupportedMediaTypeErrorDefinition";
 import ValidationErrorDefinition from "./ValidationErrorDefinition";
 
-// various error responses which are relevant for every operation
-// can be spread in the responses array of an HttpOperationDefinition
 export const sharedResponses = [
   ForbiddenErrorDefinition,
   InternalServerErrorDefinition,
@@ -367,31 +244,29 @@ export const sharedResponses = [
 # Generate with plugins:
 # - Hono: to easily provide a web server
 # - Clients: to get fitting API clients
-npx typeweaver generate --input ./api/definition --output ./api/generated --plugins clients,hono
+npx typeweaver generate --input ./api/spec/index.ts --output ./api/generated --plugins clients,hono
 ```
 
+> The CLI accepts a default export, a named `spec` export, or the module namespace itself as the
+> `SpecDefinition` entrypoint.
+
 ### 🌐 Create Hono web server
 
 ```typescript
 // api/user-handlers.ts
-import { HttpResponse, HttpStatusCode } from "@rexeus/typeweaver-core";
-import {
-  type HonoUserApiHandler,
-  type IGetUserRequest,
-  GetUserResponse,
-  GetUserSuccessResponse,
-  type ICreateUserRequest,
-  CreateUserResponse,
-  type IUpdateUserRequest,
-  UpdateUserResponse,
-  type IListUserRequest,
-  ListUserResponse,
-} from "./generated";
+import type { Context } from "hono";
+import type { HonoUserApiHandler, IGetUserRequest, GetUserResponse } from "./generated";
+import { createGetUserSuccessResponse } from "./generated";
 
+// Implement HonoUserApiHandler — the generated interface enforces
+// that every operation in the "user" resource has a handler.
 export class UserHandlers implements HonoUserApiHandler {
   public constructor() {}
 
-  public async handleGetUserRequest(request: IGetUserRequest): Promise<GetUserResponse> {
+  public async handleGetUserRequest(
+    request: IGetUserRequest,
+    context: Context
+  ): Promise<GetUserResponse> {
     // Simulate fetching user data
     const fetchedUser = {
       id: request.param.userId,
@@ -402,8 +277,7 @@ export class UserHandlers implements HonoUserApiHandler {
       updatedAt: new Date("2023-01-01").toISOString(),
     };
 
-    return new GetUserSuccessResponse({
-      statusCode: HttpStatusCode.OK,
+    return createGetUserSuccessResponse({
       header: {
         "Content-Type": "application/json",
       },
@@ -411,17 +285,9 @@ export class UserHandlers implements HonoUserApiHandler {
     });
   }
 
-  public handleCreateUserRequest(request: ICreateUserRequest): Promise<CreateUserResponse> {
-    throw new Error("Not implemented");
-  }
-
-  public handleUpdateUserRequest(request: IUpdateUserRequest): Promise<UpdateUserResponse> {
-    throw new Error("Not implemented");
-  }
-
-  public handleListUserRequest(request: IListUserRequest): Promise<ListUserResponse> {
-    throw new Error("Not implemented");
-  }
+  // Implement further handlers for each operation in the resource.
+  // TypeScript enforces the contract — every handler declared in
+  // HonoUserApiHandler must be implemented before the code compiles.
 }
 ```
 
@@ -472,23 +338,21 @@ tsx api/server.ts
 
 ```typescript
 // api/client-test.ts
-import { UserClient, GetUserRequestCommand, UserNotFoundErrorResponse } from "./generated";
+import { UserClient, GetUserRequestCommand } from "./generated";
 
 const client = new UserClient({ baseUrl: "http://localhost:3000" });
 
-try {
-  const getUserRequestCommand = new GetUserRequestCommand({
-    param: { userId: "123" },
-  });
-  const result = await client.send(getUserRequestCommand);
-
-  console.log("Successfully fetched user:", result.body);
-} catch (error) {
-  if (error instanceof UserNotFoundErrorResponse) {
-    console.error("User not found:", error.body);
-  } else {
-    console.error("Other error occurred:", error);
-  }
+const getUserRequestCommand = new GetUserRequestCommand({
+  param: { userId: "123" },
+});
+const response = await client.send(getUserRequestCommand);
+
+if (response.type === "GetUserSuccess") {
+  console.log("Successfully fetched user:", response.body);
+} else if (response.type === "UserNotFoundError") {
+  console.error("User not found:", response.body);
+} else {
+  console.error("Other error occurred:", response.type);
 }
 ```