@webpieces/http-api 0.1.0

package/README.md

@@ -0,0 +1,19 @@
+# @webpieces/http-api
+
+> HTTP API decorators for defining REST APIs
+
+Part of the [WebPieces TypeScript](https://github.com/deanhiller/webpieces-ts) framework.
+
+## Installation
+
+```bash
+npm install @webpieces/http-api
+```
+
+## Documentation
+
+See the main [WebPieces README](https://github.com/deanhiller/webpieces-ts#readme) for complete documentation and examples.
+
+## License
+
+Apache-2.0

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@webpieces/http-api",
+  "version": "0.1.0",
+  "description": "HTTP API decorators for defining REST APIs",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "author": "Dean Hiller",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deanhiller/webpieces-ts.git",
+    "directory": "packages/http/http-api"
+  },
+  "keywords": [
+    "webpieces",
+    "http",
+    "api",
+    "decorators"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {}
+}

package/src/decorators.d.ts

@@ -0,0 +1,95 @@
+import 'reflect-metadata';
+/**
+ * Metadata keys for storing API routing information.
+ * These keys are used by both server-side (routing) and client-side (client generation).
+ */
+export declare const METADATA_KEYS: {
+    API_INTERFACE: string;
+    ROUTES: string;
+    HTTP_METHOD: string;
+    PATH: string;
+};
+/**
+ * Route metadata stored on methods.
+ * Used by both server-side routing and client-side HTTP client generation.
+ */
+export interface RouteMetadata {
+    httpMethod: string;
+    path: string;
+    methodName: string;
+    parameterTypes?: any[];
+}
+/**
+ * Mark a class as an API interface.
+ * Similar to Java's JAX-RS interface pattern.
+ *
+ * This decorator is used by:
+ * - Server: RESTApiRoutes reads it to validate API interfaces
+ * - Client: Client generator reads it to identify API interfaces
+ *
+ * Usage:
+ * ```typescript
+ * @ApiInterface()
+ * abstract class SaveApiPrototype {
+ *   @Post()
+ *   @Path('/search/item')
+ *   save(request: SaveRequest): Promise<SaveResponse> {
+ *     throw new Error('Must be implemented');
+ *   }
+ * }
+ * ```
+ */
+export declare function ApiInterface(): ClassDecorator;
+/**
+ * @Get decorator for GET requests.
+ * Usage: @Get()
+ */
+export declare function Get(): MethodDecorator;
+/**
+ * @Post decorator for POST requests.
+ * Usage: @Post()
+ */
+export declare function Post(): MethodDecorator;
+/**
+ * @Put decorator for PUT requests.
+ * Usage: @Put()
+ */
+export declare function Put(): MethodDecorator;
+/**
+ * @Delete decorator for DELETE requests.
+ * Usage: @Delete()
+ */
+export declare function Delete(): MethodDecorator;
+/**
+ * @Patch decorator for PATCH requests.
+ * Usage: @Patch()
+ */
+export declare function Patch(): MethodDecorator;
+/**
+ * @Path decorator to specify the route path.
+ * Similar to JAX-RS @Path annotation.
+ *
+ * This decorator is used by:
+ * - Server: To register routes at the specified path
+ * - Client: To make HTTP requests to the specified path
+ *
+ * Usage:
+ * ```typescript
+ * @Post()
+ * @Path('/search/item')
+ * save(request: SaveRequest): Promise<SaveResponse> {
+ *   throw new Error('Must be implemented');
+ * }
+ * ```
+ */
+export declare function Path(path: string): MethodDecorator;
+/**
+ * Helper function to get all routes from an API interface class.
+ * Used by both server-side routing and client-side client generation.
+ */
+export declare function getRoutes(apiClass: any): RouteMetadata[];
+/**
+ * Helper function to check if a class is an API interface.
+ * Used by both server-side routing and client-side client generation.
+ */
+export declare function isApiInterface(apiClass: any): boolean;

package/src/decorators.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.METADATA_KEYS = void 0;
+exports.ApiInterface = ApiInterface;
+exports.Get = Get;
+exports.Post = Post;
+exports.Put = Put;
+exports.Delete = Delete;
+exports.Patch = Patch;
+exports.Path = Path;
+exports.getRoutes = getRoutes;
+exports.isApiInterface = isApiInterface;
+require("reflect-metadata");
+/**
+ * Metadata keys for storing API routing information.
+ * These keys are used by both server-side (routing) and client-side (client generation).
+ */
+exports.METADATA_KEYS = {
+    API_INTERFACE: 'webpieces:api-interface',
+    ROUTES: 'webpieces:routes',
+    HTTP_METHOD: 'webpieces:http-method',
+    PATH: 'webpieces:path',
+};
+/**
+ * Mark a class as an API interface.
+ * Similar to Java's JAX-RS interface pattern.
+ *
+ * This decorator is used by:
+ * - Server: RESTApiRoutes reads it to validate API interfaces
+ * - Client: Client generator reads it to identify API interfaces
+ *
+ * Usage:
+ * ```typescript
+ * @ApiInterface()
+ * abstract class SaveApiPrototype {
+ *   @Post()
+ *   @Path('/search/item')
+ *   save(request: SaveRequest): Promise<SaveResponse> {
+ *     throw new Error('Must be implemented');
+ *   }
+ * }
+ * ```
+ */
+function ApiInterface() {
+    return (target) => {
+        Reflect.defineMetadata(exports.METADATA_KEYS.API_INTERFACE, true, target);
+        // Initialize routes array if not exists
+        if (!Reflect.hasMetadata(exports.METADATA_KEYS.ROUTES, target)) {
+            Reflect.defineMetadata(exports.METADATA_KEYS.ROUTES, [], target);
+        }
+    };
+}
+/**
+ * Internal helper to mark a method with an HTTP method.
+ * Used by @Get, @Post, @Put, @Delete, @Patch decorators.
+ */
+function httpMethod(method) {
+    return (target, propertyKey, descriptor) => {
+        // For static methods, target is the constructor itself
+        // For instance methods, target is the prototype
+        const metadataTarget = typeof target === 'function' ? target : target.constructor;
+        const existingMetadata = Reflect.getMetadata(exports.METADATA_KEYS.ROUTES, metadataTarget) || [];
+        // Find or create route metadata for this method
+        let routeMetadata = existingMetadata.find((r) => r.methodName === propertyKey);
+        if (!routeMetadata) {
+            routeMetadata = {
+                httpMethod: '',
+                path: '',
+                methodName: propertyKey,
+            };
+            existingMetadata.push(routeMetadata);
+        }
+        routeMetadata.httpMethod = method;
+        // Get parameter types
+        const paramTypes = Reflect.getMetadata('design:paramtypes', target, propertyKey);
+        if (paramTypes) {
+            routeMetadata.parameterTypes = paramTypes;
+        }
+        Reflect.defineMetadata(exports.METADATA_KEYS.ROUTES, existingMetadata, metadataTarget);
+    };
+}
+/**
+ * @Get decorator for GET requests.
+ * Usage: @Get()
+ */
+function Get() {
+    return httpMethod('GET');
+}
+/**
+ * @Post decorator for POST requests.
+ * Usage: @Post()
+ */
+function Post() {
+    return httpMethod('POST');
+}
+/**
+ * @Put decorator for PUT requests.
+ * Usage: @Put()
+ */
+function Put() {
+    return httpMethod('PUT');
+}
+/**
+ * @Delete decorator for DELETE requests.
+ * Usage: @Delete()
+ */
+function Delete() {
+    return httpMethod('DELETE');
+}
+/**
+ * @Patch decorator for PATCH requests.
+ * Usage: @Patch()
+ */
+function Patch() {
+    return httpMethod('PATCH');
+}
+/**
+ * @Path decorator to specify the route path.
+ * Similar to JAX-RS @Path annotation.
+ *
+ * This decorator is used by:
+ * - Server: To register routes at the specified path
+ * - Client: To make HTTP requests to the specified path
+ *
+ * Usage:
+ * ```typescript
+ * @Post()
+ * @Path('/search/item')
+ * save(request: SaveRequest): Promise<SaveResponse> {
+ *   throw new Error('Must be implemented');
+ * }
+ * ```
+ */
+function Path(path) {
+    return (target, propertyKey, descriptor) => {
+        // For static methods, target is the constructor itself
+        // For instance methods, target is the prototype
+        const metadataTarget = typeof target === 'function' ? target : target.constructor;
+        const existingMetadata = Reflect.getMetadata(exports.METADATA_KEYS.ROUTES, metadataTarget) || [];
+        // Find or create route metadata for this method
+        let routeMetadata = existingMetadata.find((r) => r.methodName === propertyKey);
+        if (!routeMetadata) {
+            routeMetadata = {
+                httpMethod: '',
+                path: '',
+                methodName: propertyKey,
+            };
+            existingMetadata.push(routeMetadata);
+        }
+        routeMetadata.path = path;
+        Reflect.defineMetadata(exports.METADATA_KEYS.ROUTES, existingMetadata, metadataTarget);
+    };
+}
+/**
+ * Helper function to get all routes from an API interface class.
+ * Used by both server-side routing and client-side client generation.
+ */
+function getRoutes(apiClass) {
+    const routes = Reflect.getMetadata(exports.METADATA_KEYS.ROUTES, apiClass);
+    return routes || [];
+}
+/**
+ * Helper function to check if a class is an API interface.
+ * Used by both server-side routing and client-side client generation.
+ */
+function isApiInterface(apiClass) {
+    return Reflect.getMetadata(exports.METADATA_KEYS.API_INTERFACE, apiClass) === true;
+}
+//# sourceMappingURL=decorators.js.map

package/src/decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../../../../packages/http/http-api/src/decorators.ts"],"names":[],"mappings":"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"}

package/src/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @webpieces/http-api
+ *
+ * Core HTTP API definition package.
+ * Contains decorators and utilities for defining HTTP APIs.
+ *
+ * This package is used by:
+ * - @webpieces/http-routing (server-side): Routes HTTP requests to controllers
+ * - @webpieces/http-client (client-side): Generates HTTP clients from API definitions
+ *
+ * Architecture:
+ * ```
+ * http-api (defines the contract)
+ *    ↑
+ *    ├── http-routing (server: contract → handlers)
+ *    └── http-client (client: contract → HTTP requests)
+ * ```
+ */
+export { ApiInterface, Get, Post, Put, Delete, Patch, Path, getRoutes, isApiInterface, RouteMetadata, METADATA_KEYS, } from './decorators';
+export { ValidateImplementation } from './validators';

package/src/index.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * @webpieces/http-api
+ *
+ * Core HTTP API definition package.
+ * Contains decorators and utilities for defining HTTP APIs.
+ *
+ * This package is used by:
+ * - @webpieces/http-routing (server-side): Routes HTTP requests to controllers
+ * - @webpieces/http-client (client-side): Generates HTTP clients from API definitions
+ *
+ * Architecture:
+ * ```
+ * http-api (defines the contract)
+ *    ↑
+ *    ├── http-routing (server: contract → handlers)
+ *    └── http-client (client: contract → HTTP requests)
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.METADATA_KEYS = exports.isApiInterface = exports.getRoutes = exports.Path = exports.Patch = exports.Delete = exports.Put = exports.Post = exports.Get = exports.ApiInterface = void 0;
+// API definition decorators
+var decorators_1 = require("./decorators");
+Object.defineProperty(exports, "ApiInterface", { enumerable: true, get: function () { return decorators_1.ApiInterface; } });
+Object.defineProperty(exports, "Get", { enumerable: true, get: function () { return decorators_1.Get; } });
+Object.defineProperty(exports, "Post", { enumerable: true, get: function () { return decorators_1.Post; } });
+Object.defineProperty(exports, "Put", { enumerable: true, get: function () { return decorators_1.Put; } });
+Object.defineProperty(exports, "Delete", { enumerable: true, get: function () { return decorators_1.Delete; } });
+Object.defineProperty(exports, "Patch", { enumerable: true, get: function () { return decorators_1.Patch; } });
+Object.defineProperty(exports, "Path", { enumerable: true, get: function () { return decorators_1.Path; } });
+Object.defineProperty(exports, "getRoutes", { enumerable: true, get: function () { return decorators_1.getRoutes; } });
+Object.defineProperty(exports, "isApiInterface", { enumerable: true, get: function () { return decorators_1.isApiInterface; } });
+Object.defineProperty(exports, "METADATA_KEYS", { enumerable: true, get: function () { return decorators_1.METADATA_KEYS; } });
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/http/http-api/src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAEH,4BAA4B;AAC5B,2CAYsB;AAXpB,0GAAA,YAAY,OAAA;AACZ,iGAAA,GAAG,OAAA;AACH,kGAAA,IAAI,OAAA;AACJ,iGAAA,GAAG,OAAA;AACH,oGAAA,MAAM,OAAA;AACN,mGAAA,KAAK,OAAA;AACL,kGAAA,IAAI,OAAA;AACJ,uGAAA,SAAS,OAAA;AACT,4GAAA,cAAc,OAAA;AAEd,2GAAA,aAAa,OAAA"}

package/src/validators.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Type-level validator to ensure a class implements all methods from an interface.
+ *
+ * This validator provides compile-time verification that an implementation
+ * (e.g., controller, client, mock) fully implements an API interface.
+ *
+ * Usage in server-side controllers:
+ * ```typescript
+ * export class SaveController extends SaveApiPrototype implements SaveApi {
+ *   // Compile-time check: ensures all SaveApi methods are implemented
+ *   private readonly __validator!: ValidateImplementation<SaveController, SaveApi>;
+ *
+ *   save(request: SaveRequest): Promise<SaveResponse> {
+ *     // implementation
+ *   }
+ * }
+ * ```
+ *
+ * Usage in client-side implementations:
+ * ```typescript
+ * export class MockSaveClient implements SaveApi {
+ *   private readonly __validator!: ValidateImplementation<MockSaveClient, SaveApi>;
+ *
+ *   save(request: SaveRequest): Promise<SaveResponse> {
+ *     // mock implementation
+ *   }
+ * }
+ * ```
+ *
+ * Benefits:
+ * - Compile error if any interface method is missing
+ * - Compile error if method signatures don't match
+ * - Works with controllers, clients, mocks, stubs, etc.
+ * - Type-safe contract enforcement
+ *
+ * Note: The `!` assertion is safe because this field is never accessed at runtime.
+ * It only exists for compile-time type checking.
+ */
+export type ValidateImplementation<TImpl, TInterface> = {
+    [K in keyof TInterface]: K extends keyof TImpl ? TImpl[K] extends TInterface[K] ? TInterface[K] : never : never;
+};

package/src/validators.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=validators.js.map

package/src/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../../../../../packages/http/http-api/src/validators.ts"],"names":[],"mappings":""}