@webda/core 4.0.0-beta.2 → 4.0.0-beta.3

package/lib/rest/restoperationstransport.service.d.ts

@@ -0,0 +1,193 @@
+import { TransformCaseType } from "@webda/utils";
+import { OperationsTransport, OperationsTransportParameters } from "../services/operationstransport.js";
+import { OperationDefinition } from "../core/icore.js";
+import { WebContext } from "../contexts/webcontext.js";
+import type { ModelClass } from "@webda/models";
+import type { ModelAction } from "../models/types.js";
+import type { ModelGraphBehaviorDefinition, ModelMetadata } from "@webda/compiler";
+/**
+ * Parameters for RESTOperationsTransport
+ */
+export declare class RESTOperationsTransportParameters extends OperationsTransportParameters {
+    /**
+     * Expose the OpenAPI
+     *
+     * @default true if debug false otherwise
+     */
+    exposeOpenAPI?: boolean;
+    /**
+     * Swagger version to use
+     *
+     * https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.19.5/swagger-ui.css
+     * https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.19.5/swagger-ui-bundle.js
+     * https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.19.5/swagger-ui-standalone-preset.js
+     *
+     * TODO Add renovatebot regex
+     */
+    swaggerVersion: string;
+    /**
+     * Base URL for the REST API
+     */
+    url: string;
+    /**
+     * Transform the name of the model to be used in the URL
+     *
+     * @see https://blog.boot.dev/clean-code/casings-in-coding/
+     * @default camelCase
+     */
+    nameTransformer?: TransformCaseType;
+    /**
+     * Method used for query objects
+     *
+     * @default "PUT"
+     */
+    queryMethod?: "PUT" | "GET";
+    /**
+     * Load parameters with defaults
+     * @param params - the service parameters
+     * @returns this for chaining
+     */
+    load(params?: any): this;
+}
+/**
+ * REST transport that exposes model operations as RESTful HTTP routes.
+ *
+ * Instead of iterating operations flat, it walks the model tree
+ * (parent/child relationships) to build nested URL prefixes like
+ * `/companies/{pid.0}/users/{uuid}`.
+ *
+ * @WebdaModda
+ */
+export declare class RESTOperationsTransport<T extends RESTOperationsTransportParameters = RESTOperationsTransportParameters> extends OperationsTransport<T> {
+    /**
+     * OpenAPI cache
+     */
+    openapiContent: string;
+    /**
+     * Transform name using configured casing
+     * @param name - the name to transform
+     * @returns the transformed name
+     */
+    transformName(name: string): string;
+    /**
+     * Resolve the service - set up OpenAPI route if configured
+     * @returns this for chaining
+     */
+    resolve(): this;
+    /**
+     * Override initTransport to walk the model tree instead of flat iteration.
+     * For each model, we look up its operations and register REST routes.
+     */
+    protected initTransport(): void;
+    /**
+     * Expose service/bean operations that have rest hints but aren't tied to model CRUD.
+     * These are operations registered by Service.initOperations() from @Operation decorators.
+     * @param operations - the filtered operations map
+     */
+    protected exposeServiceOperations(operations: Record<string, OperationDefinition>): void;
+    /**
+     * Recursively walk a model and its children, registering routes at each level
+     * @param model - the model class
+     * @param metadata - model metadata
+     * @param operations - filtered operations map
+     * @param basePrefix - URL prefix from parent context
+     * @param depth - nesting depth for parent id parameters
+     */
+    protected walkModel(model: ModelClass, metadata: ModelMetadata, operations: Record<string, OperationDefinition>, basePrefix: string, depth: number): void;
+    /**
+     * Register query route for a model
+     * @param prefix - the URL prefix for this model
+     * @param plural - the pluralized model name
+     * @param shortId - the short model identifier
+     * @param identifier - the full model identifier
+     * @param depth - nesting depth for parent id parameters
+     * @param injectAttribute - parent attribute to inject in queries
+     * @param operations - the filtered operations map
+     */
+    protected exposeQueryRoute(prefix: string, plural: string, shortId: string, identifier: string, depth: number, injectAttribute: string | undefined, operations: Record<string, OperationDefinition>): void;
+    /**
+     * Register create route for a model
+     * @param prefix - the URL prefix for this model
+     * @param shortId - the short model identifier
+     * @param identifier - the full model identifier
+     * @param depth - nesting depth for parent id parameters
+     * @param injectAttribute - parent attribute to inject on create
+     * @param operations - the filtered operations map
+     */
+    protected exposeCreateRoute(prefix: string, shortId: string, identifier: string, depth: number, injectAttribute: string | undefined, operations: Record<string, OperationDefinition>): void;
+    /**
+     * Register delete route for a model
+     * @param prefix - the URL prefix for this model
+     * @param shortId - the short model identifier
+     * @param identifier - the full model identifier
+     * @param operations - the filtered operations map
+     */
+    protected exposeDeleteRoute(prefix: string, shortId: string, identifier: string, operations: Record<string, OperationDefinition>): void;
+    /**
+     * Register update (PUT) and patch (PATCH) routes for a model
+     * @param prefix - the URL prefix for this model
+     * @param shortId - the short model identifier
+     * @param identifier - the full model identifier
+     * @param operations - the filtered operations map
+     */
+    protected exposeUpdateRoute(prefix: string, shortId: string, identifier: string, operations: Record<string, OperationDefinition>): void;
+    /**
+     * Register get route for a model
+     * @param prefix - the URL prefix for this model
+     * @param shortId - the short model identifier
+     * @param identifier - the full model identifier
+     * @param operations - the filtered operations map
+     */
+    protected exposeGetRoute(prefix: string, shortId: string, identifier: string, operations: Record<string, OperationDefinition>): void;
+    /**
+     * Register action route for a model
+     * @param prefix - the URL prefix for this model
+     * @param shortId - the short model identifier
+     * @param identifier - the full model identifier
+     * @param actionName - the name of the action
+     * @param action - the action definition
+     * @param depth - nesting depth for parent id parameters
+     * @param injectAttribute - parent attribute to inject
+     */
+    protected exposeActionRoute(prefix: string, shortId: string, identifier: string, actionName: string, action: ModelAction, depth: number, injectAttribute: string | undefined): void;
+    /**
+     * Register routes for every `@Action` on every Behavior attribute of a
+     * model. The default URL pattern is `{prefix}/{uuid}/{attribute}.{action}`
+     * (PUT) — the dot disambiguates Behavior calls from nested-resource routing.
+     *
+     * Authors can override the route via `@Action({ rest: { route, method } })`.
+     * `addBehaviorOperations` resolves that hint and writes the final
+     * `rest.method`/`rest.path` on the registered operation; this method just
+     * mirrors what's there, falling back to the dot-notation default if no
+     * hint was set.
+     *
+     * Each route dispatches the registered behavior operation
+     * (`{ShortId}.{AttributeCap}.{ActionCap}`). The dispatcher itself
+     * (`modelBehaviorAction`) handles model load, `canAct` gating, and method
+     * invocation — this method only wires the HTTP surface.
+     *
+     * Schema decoration on the OpenAPI doc is best-effort — we lean on
+     * `hasSchema()` (the AJV registry) to decide whether to emit
+     * `requestBody` / `responses` `$ref`s.
+     *
+     * @param prefix - the URL prefix for this model (e.g. `/api/users`)
+     * @param shortId - the short model identifier (e.g. `User`)
+     * @param identifier - the full model identifier (e.g. `MyApp/User`) — accepted
+     *   for symmetry with `walkModel`'s caller signature even though we don't currently use it
+     * @param name - the model display name used in OpenAPI tags
+     * @param behavior - the Behavior attribute relation to expose
+     */
+    protected exposeBehaviorRoutes(prefix: string, shortId: string, identifier: string, name: string, behavior: ModelGraphBehaviorDefinition): void;
+    /**
+     * No-op: route exposure is handled entirely by initTransport's tree walk
+     * @param _operationId - the operation identifier (unused)
+     * @param _definition - the operation definition (unused)
+     */
+    exposeOperation(_operationId: string, _definition: OperationDefinition): void;
+    /**
+     * Serve the openapi with the swagger-ui
+     * @param ctx - the web context
+     */
+    openapi(ctx: WebContext): Promise<void>;
+}
+//# sourceMappingURL=restoperationstransport.service.d.ts.map

package/lib/rest/restoperationstransport.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restoperationstransport.service.d.ts","sourceRoot":"","sources":["../../src/rest/restoperationstransport.service.ts"],"names":[],"mappings":"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"}