CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-azure--core-client

Core library for interfacing with AutoRest generated code

—

Pending
Overview
Eval results
Files

operations.mddocs/

Operation Specifications

Structured definitions of HTTP operations derived from OpenAPI/Swagger specifications. Operation specifications define all aspects of an HTTP request including parameters, serialization, URL construction, headers, and response handling.

Capabilities

Operation Specification

Complete specification for an HTTP operation that defines request structure, parameter mapping, serialization rules, and response handling.

/**
 * Complete specification for an HTTP operation derived from OpenAPI/Swagger
 */
interface OperationSpec {
  /** Serializer instance for this operation */
  serializer: Serializer;
  
  /** HTTP method for the operation */
  httpMethod: HttpMethods;
  
  /** URL template with placeholders (e.g., "/users/{userId}") */
  baseUrl?: string;
  
  /** Fixed path component for URL construction */
  path?: string;
  
  /** Content-Type header for requests */
  contentType?: string;
  
  /** Media type for request body */
  mediaType?: string;
  
  /** Request body parameter definition */
  requestBody?: OperationParameter;
  
  /** Whether operation uses XML format */
  isXML?: boolean;
  
  /** Parameters for URL template substitution */
  urlParameters?: ReadonlyArray<OperationURLParameter>;
  
  /** Parameters for query string construction */
  queryParameters?: ReadonlyArray<OperationQueryParameter>;
  
  /** Parameters for HTTP headers */
  headerParameters?: ReadonlyArray<OperationParameter>;
  
  /** Parameters for form data */
  formDataParameters?: ReadonlyArray<OperationParameter>;
  
  /** Response mappings by HTTP status code */
  responses: { [responseCode: string]: OperationResponseMap };
}

Operation Arguments

Container for parameter values passed to an operation, including both named parameters and operation options.

/**
 * Arguments passed to an operation call
 */
interface OperationArguments {
  /** Named parameter values keyed by parameter name */
  [parameterName: string]: unknown;
  
  /** Optional operation configuration */
  options?: OperationOptions;
}

Operation Options

Base options available for all operations, providing control over request behavior, cancellation, tracing, and callbacks.

/**
 * Base options available for all operations
 */
interface OperationOptions {
  /** Signal for request cancellation */
  abortSignal?: AbortSignalLike;
  
  /** HTTP request configuration */
  requestOptions?: OperationRequestOptions;
  
  /** Distributed tracing options */
  tracingOptions?: OperationTracingOptions;
  
  /** Serialization configuration */
  serializerOptions?: SerializerOptions;
  
  /** Callback for each response received */
  onResponse?: RawResponseCallback;
}

Parameter Types

Base Operation Parameter

Foundation interface for all operation parameters, defining how to locate and serialize parameter values.

/**
 * Base interface for operation parameter definitions
 */
interface OperationParameter {
  /** Path to parameter value in operation arguments */
  parameterPath: ParameterPath;
  
  /** Mapper for parameter serialization */
  mapper: Mapper;
}

URL Parameters

Parameters used for URL template substitution, replacing placeholders in the URL path.

/**
 * Parameter used for URL template substitution
 */
interface OperationURLParameter extends OperationParameter {
  /** Whether to skip URL encoding for this parameter */
  skipEncoding?: boolean;
}

Query Parameters

Parameters used for query string construction with support for array serialization formats.

/**
 * Parameter used for query string construction
 */
interface OperationQueryParameter extends OperationParameter {
  /** Whether to skip URL encoding for this parameter */
  skipEncoding?: boolean;
  
  /** How to join array values in query strings */
  collectionFormat?: QueryCollectionFormat;
}

/**
 * Format specifier for joining array values in query parameters
 */
type QueryCollectionFormat = "CSV" | "SSV" | "TSV" | "Pipes" | "Multi";

Parameter Path

Flexible path specification for locating parameter values in nested argument objects.

/**
 * Path specification for reaching a property value in nested objects
 */
type ParameterPath = string | string[] | { [propertyName: string]: ParameterPath };

Request and Response Handling

Operation Request Types

/**
 * HTTP request object for operations (alias for PipelineRequest)
 */
type OperationRequest = PipelineRequest;

/**
 * Metadata attached to requests for response processing
 */
interface OperationRequestInfo {
  /** Operation specification for response parsing */
  operationSpec?: OperationSpec;
  
  /** Original arguments for context */
  operationArguments?: OperationArguments;
  
  /** Custom response mapper function */
  operationResponseGetter?: (
    operationSpec: OperationSpec,
    response: PipelineResponse
  ) => undefined | OperationResponseMap;
  
  /** Whether to deserialize response */
  shouldDeserialize?: boolean | ((response: PipelineResponse) => boolean);
}

/**
 * HTTP-level options for operation requests
 */
interface OperationRequestOptions {
  /** Additional headers to include */
  customHeaders?: { [headerName: string]: string };
  
  /** Request timeout in milliseconds */
  timeout?: number;
  
  /** Upload progress callback */
  onUploadProgress?: (progress: TransferProgressEvent) => void;
  
  /** Download progress callback */
  onDownloadProgress?: (progress: TransferProgressEvent) => void;
  
  /** Control response deserialization */
  shouldDeserialize?: boolean | ((response: PipelineResponse) => boolean);
  
  /** Allow HTTP (non-HTTPS) connections */
  allowInsecureConnection?: boolean;
}

Response Handling

/**
 * Response mapping configuration for a specific status code
 */
interface OperationResponseMap {
  /** Mapper for response headers */
  headersMapper?: Mapper;
  
  /** Mapper for response body */
  bodyMapper?: Mapper;
  
  /** Whether this status code represents an error */
  isError?: boolean;
}

/**
 * Complete HTTP response with parsed data
 */
interface FullOperationResponse extends PipelineResponse {
  /** Parsed response headers */
  parsedHeaders?: { [key: string]: unknown };
  
  /** Parsed response body */
  parsedBody?: unknown;
  
  /** Original request that generated this response */
  request: OperationRequest;
}

/**
 * Callback invoked for each HTTP response received
 */
type RawResponseCallback = (
  rawResponse: FullOperationResponse,
  flatResponse: unknown,
  error?: unknown
) => void;

Usage Examples

Basic Operation Specification

import { createSerializer } from "@azure/core-client";
import type { OperationSpec } from "@azure/core-client";

const serializer = createSerializer();

// Simple GET operation
const getUserSpec: OperationSpec = {
  httpMethod: "GET",
  path: "/users/{userId}",
  serializer,
  urlParameters: [{
    parameterPath: "userId",
    mapper: {
      serializedName: "userId",
      type: { name: "String" }
    }
  }],
  responses: {
    200: {
      bodyMapper: {
        type: { name: "Composite" },
        modelProperties: {
          id: { serializedName: "id", type: { name: "String" } },
          name: { serializedName: "name", type: { name: "String" } },
          email: { serializedName: "email", type: { name: "String" } }
        }
      }
    },
    404: {
      isError: true
    }
  }
};

// Use with ServiceClient
const result = await client.sendOperationRequest(
  { userId: "123" }, 
  getUserSpec
);

POST Operation with Request Body

import { createSerializer } from "@azure/core-client";
import type { OperationSpec } from "@azure/core-client";

const serializer = createSerializer();

const createUserSpec: OperationSpec = {
  httpMethod: "POST",
  path: "/users",
  contentType: "application/json",
  serializer,
  requestBody: {
    parameterPath: "user",
    mapper: {
      type: { name: "Composite" },
      modelProperties: {
        name: { 
          serializedName: "name", 
          required: true,
          type: { name: "String" }
        },
        email: { 
          serializedName: "email", 
          required: true,
          type: { name: "String" }
        }
      }
    }
  },
  responses: {
    201: {
      bodyMapper: {
        type: { name: "Composite" },
        modelProperties: {
          id: { serializedName: "id", type: { name: "String" } },
          name: { serializedName: "name", type: { name: "String" } },
          email: { serializedName: "email", type: { name: "String" } }
        }
      }
    }
  }
};

// Usage
const newUser = await client.sendOperationRequest(
  { 
    user: { 
      name: "Alice Smith", 
      email: "alice@example.com" 
    } 
  },
  createUserSpec
);

Operation with Query Parameters

import { createSerializer } from "@azure/core-client";
import type { OperationSpec } from "@azure/core-client";

const serializer = createSerializer();

const listUsersSpec: OperationSpec = {
  httpMethod: "GET",
  path: "/users",
  serializer,
  queryParameters: [
    {
      parameterPath: "pageSize",
      mapper: {
        serializedName: "page_size",
        type: { name: "Number" }
      }
    },
    {
      parameterPath: "filter",
      mapper: {
        serializedName: "filter",
        type: { name: "String" }
      }
    },
    {
      parameterPath: "tags",
      collectionFormat: "CSV",
      mapper: {
        serializedName: "tags",
        type: {
          name: "Sequence",
          element: { type: { name: "String" } }
        }
      }
    }
  ],
  responses: {
    200: {
      bodyMapper: {
        type: { name: "Composite" },
        modelProperties: {
          users: {
            serializedName: "users",
            type: {
              name: "Sequence",
              element: {
                type: { name: "Composite" },
                modelProperties: {
                  id: { serializedName: "id", type: { name: "String" } },
                  name: { serializedName: "name", type: { name: "String" } }
                }
              }
            }
          },
          nextPageToken: {
            serializedName: "next_page_token",
            type: { name: "String" }
          }
        }
      }
    }
  }
};

// Usage
const users = await client.sendOperationRequest(
  {
    pageSize: 10,
    filter: "active",
    tags: ["premium", "verified"]
  },
  listUsersSpec
);
// Generates URL: /users?page_size=10&filter=active&tags=premium,verified

Operation with Headers

import { createSerializer } from "@azure/core-client";
import type { OperationSpec } from "@azure/core-client";

const serializer = createSerializer();

const uploadFileSpec: OperationSpec = {
  httpMethod: "PUT",
  path: "/files/{fileName}",
  serializer,
  urlParameters: [{
    parameterPath: "fileName",
    mapper: {
      serializedName: "fileName",
      type: { name: "String" }
    }
  }],
  headerParameters: [
    {
      parameterPath: "contentType",
      mapper: {
        serializedName: "content-type",
        type: { name: "String" }
      }
    },
    {
      parameterPath: "contentLength",
      mapper: {
        serializedName: "content-length",
        type: { name: "Number" }
      }
    }
  ],
  requestBody: {
    parameterPath: "fileContent",
    mapper: {
      type: { name: "Stream" }
    }
  },
  responses: {
    200: {
      headersMapper: {
        type: { name: "Composite" },
        modelProperties: {
          etag: {
            serializedName: "etag",
            type: { name: "String" }
          }
        }
      }
    }
  }
};

Operation with Complex Response Handling

import { createSerializer } from "@azure/core-client";
import type { OperationSpec, RawResponseCallback } from "@azure/core-client";

const serializer = createSerializer();

// Custom response callback
const responseCallback: RawResponseCallback = (rawResponse, flatResponse, error) => {
  console.log(`Request ID: ${rawResponse.headers.get("x-ms-request-id")}`);
  if (error) {
    console.error("Operation failed:", error);
  }
};

const complexOperationSpec: OperationSpec = {
  httpMethod: "POST",
  path: "/complex-operation",
  serializer,
  responses: {
    200: {
      bodyMapper: {
        type: { name: "Composite" },
        modelProperties: {
          result: { serializedName: "result", type: { name: "String" } }
        }
      },
      headersMapper: {
        type: { name: "Composite" },
        modelProperties: {
          operationId: {
            serializedName: "x-operation-id",
            type: { name: "String" }
          }
        }
      }
    },
    202: {
      bodyMapper: {
        type: { name: "Composite" },
        modelProperties: {
          status: { serializedName: "status", type: { name: "String" } },
          location: { serializedName: "location", type: { name: "String" } }
        }
      }
    }
  }
};

// Usage with callback
const result = await client.sendOperationRequest(
  { 
    options: { 
      onResponse: responseCallback,
      requestOptions: {
        timeout: 30000
      }
    } 
  },
  complexOperationSpec
);

Integration with ServiceClient

Operation specifications work seamlessly with ServiceClient for complete request/response handling:

import { ServiceClient, createSerializer } from "@azure/core-client";
import type { OperationSpec, OperationArguments } from "@azure/core-client";

class MyApiClient extends ServiceClient {
  private serializer = createSerializer();

  async getResource(id: string): Promise<Resource> {
    const operationSpec: OperationSpec = {
      httpMethod: "GET",
      path: "/resources/{id}",
      serializer: this.serializer,
      urlParameters: [{
        parameterPath: "id",
        mapper: { serializedName: "id", type: { name: "String" } }
      }],
      responses: {
        200: { bodyMapper: this.getResourceMapper() }
      }
    };

    return this.sendOperationRequest({ id }, operationSpec);
  }

  private getResourceMapper() {
    return {
      type: { name: "Composite" },
      modelProperties: {
        id: { serializedName: "id", type: { name: "String" } },
        name: { serializedName: "name", type: { name: "String" } },
        properties: {
          serializedName: "properties",
          type: {
            name: "Dictionary",
            value: { type: { name: "String" } }
          }
        }
      }
    };
  }
}

Install with Tessl CLI

npx tessl i tessl/npm-azure--core-client

docs

authentication.md

index.md

operations.md

pipeline.md

policies.md

serialization.md

service-client.md

tile.json