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

package/lib/core/operations.d.ts

@@ -0,0 +1,181 @@
+import { OperationDefinition } from "./icore.js";
+import { OperationContext } from "../contexts/operationcontext.js";
+import type { Service } from "../services/service.js";
+import type { Model } from "@webda/models";
+type OperationTarget = Service | Model | typeof Service | typeof Model;
+/**
+ * Check whether the context's session is allowed to call an operation
+ *
+ * Unlike {@link checkOperation}, this never throws: unknown operations and
+ * permission queries that cannot be evaluated return false.
+ *
+ * @param context - the execution context holding the session
+ * @param operationId - the operation identifier
+ * @returns true if the operation exists and its permission (if any) accepts the session
+ */
+export declare function canCallOperation(context: OperationContext, operationId: string): boolean;
+/**
+ * Target object of an operation, used by listeners such as the audit log
+ */
+export type OperationSubject = {
+    /** Model identifier, e.g. `WebdaSample/Post` */
+    model: string;
+    /** Canonical primary key, see `serializeSubjectKey` */
+    key: string;
+};
+/**
+ * Serialize a primary key to the canonical string identifying an operation subject.
+ *
+ * A single-field key is its string value; a composite key is the JSON array of its
+ * field values in `pkFields` order, so plain input objects and `getPrimaryKey()`
+ * results (including relation links) produce the same string.
+ * @param pkFields - the model primary key fields
+ * @param key - a scalar key, or an object holding the key fields
+ * @returns the canonical key, or undefined when a field is missing
+ */
+export declare function serializeSubjectKey(pkFields: readonly string[], key: unknown): string | undefined;
+/**
+ * Turn a subject key sent by a client into a key usable with `Model.ref()`.
+ *
+ * Accepts the scalar value, an object of key fields, or for composite keys the
+ * canonical JSON array produced by `serializeSubjectKey`.
+ * @param pkFields - the model primary key fields
+ * @param key - the key as received
+ * @returns the key, or undefined when it does not match `pkFields`
+ */
+export declare function parseSubjectKey(pkFields: readonly string[], key: unknown): string | Record<string, string> | undefined;
+/**
+ * Declare the object the current operation acts on, when the framework cannot
+ * derive it: a service operation such as `Publisher.PublishPost(postId)`.
+ * Listeners such as the audit log record it like a derived subject, and it
+ * takes precedence over one. Call it from the operation (or anything it calls);
+ * outside an operation it does nothing.
+ *
+ * @param subject - a model instance, or `{ model, key }` with a model class or
+ *   identifier and its primary key (scalar, object of key fields, or canonical string)
+ * @throws Error if the model is unknown or the key does not match its primary key
+ */
+export declare function setOperationSubject(subject: Model | {
+    model: string | any;
+    key: unknown;
+}): void;
+/**
+ * Find the object an operation targets
+ *
+ * - model instance operation: the model and the key it was called with
+ * - operation with `context.model` (DomainService CRUD, behaviors): the key fields from
+ *   the resolved input or the request parameters, or for `Create` the created object
+ * - queries, static model operations and plain service operations: none
+ * @param context - the operation context
+ * @param operation - the operation definition
+ * @param args - the arguments the operation was called with
+ * @param result - the operation result, when it succeeded
+ * @returns the subject, or undefined when the operation has no single target
+ */
+export declare function resolveOperationSubject(context: OperationContext, operation: OperationDefinition, args: any[], result?: any): OperationSubject | undefined;
+/**
+ * Resolve method arguments from the OperationContext using the operation's input schema metadata.
+ *
+ * The REST transport merges path/query params into the context so that `context.getParameters()`
+ * contains URL-derived values (e.g., `{uuid}`) while `context.getInput()` contains the request
+ * body. This function merges both sources (body overrides params) and extracts arguments based
+ * on the `input` schema property names and order.
+ *
+ * @param context - the execution context
+ * @param operation - the operation definition
+ * @returns an array of resolved arguments to pass to the operation method
+ */
+export declare function resolveArguments(context: OperationContext, operation: OperationDefinition): Promise<any[]>;
+/**
+ * Call an operation within the framework
+ * @param context - the execution context
+ * @param operationId - the operation identifier
+ */
+export declare function callOperation(context: OperationContext, operationId: string): Promise<void>;
+/**
+ * Get available operations
+ * @returns the result
+ */
+export declare function listOperations(): {
+    [key: string]: Omit<OperationDefinition, "service" | "method">;
+};
+/**
+ * Get available operations with full details including service/method.
+ * Intended for debug/introspection only.
+ * @returns operations map with all fields
+ */
+export declare function listFullOperations(): {
+    [key: string]: OperationDefinition;
+};
+/**
+ * Register a new operation within the app
+ * @param operationId - the operation identifier
+ * @param definition - the definition object
+ */
+export declare function registerOperation(operationId: string, definition: Omit<OperationDefinition, "id" | "input" | "output"> & {
+    input?: string;
+    output?: string;
+}): void;
+/**
+ * Wrapper concept for an operation
+ *
+ * Wrapper will launch the operation but they can wrap it with additional logic
+ * It allows to set some asyncStorage
+ *
+ * Logging configuration per Operation
+ * Metrics, Tracing
+ *
+ */
+interface OperationParameters {
+    /**
+     * A unique operation id
+     *
+     * If a . is present it will be considered as a unique operation
+     * If no . is present the operation will be prefixed with the Service name or the Model name
+     */
+    id?: string;
+    /**
+     * Short summary of the operation
+     */
+    summary?: string;
+    /**
+     * Full description of the operation
+     */
+    description?: string;
+    /**
+     * Categorization tags for the operation
+     */
+    tags?: string[];
+    /**
+     * Hide the operation from transport exposure
+     */
+    hidden?: boolean;
+    /**
+     * Mark the operation as deprecated
+     */
+    deprecated?: boolean;
+    /**
+     * Permission query to check before executing the operation
+     */
+    permissionQuery?: string;
+    /**
+     * REST transport hints
+     */
+    rest?: OperationDefinition["rest"];
+    /**
+     * GraphQL transport hints
+     */
+    graphql?: OperationDefinition["graphql"];
+    /**
+     * gRPC transport hints
+     */
+    grpc?: OperationDefinition["grpc"];
+    /**
+     * MCP transport hints
+     */
+    mcp?: OperationDefinition["mcp"];
+}
+declare function Operation<T = {}>(options?: T & OperationParameters): (target: (this: OperationTarget, ...args: any) => any, context: ClassMethodDecoratorContext) => void;
+declare function Operation(target: (this: OperationTarget, ...args: any) => any, context: ClassMethodDecoratorContext): void;
+export { Operation };
+//# sourceMappingURL=operations.d.ts.map

package/lib/core/operations.d.ts.map

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