Azure ms-rest Client Runtime

Common errors

• TypeError: msRest.loginWithServicePrincipalSecret is not a function

  cause `ms-rest` itself does not contain authentication methods. These are provided by related packages like `ms-rest-azure` or `@azure/ms-rest-nodeauth`.
  fix Import authentication methods from `ms-rest-azure` or `@azure/ms-rest-nodeauth`. For modern applications, migrate to `@azure/identity`. Example: `const msRestAzure = require('ms-rest-azure'); msRestAzure.loginWithServicePrincipalSecret(...)` or `import { DefaultAzureCredential } from '@azure/identity';`

• ERR_REQUIRE_ESM: Must use import to load ES Module

  cause This error occurs when a CommonJS module (like `ms-rest`) attempts to `require()` a package that has transitioned to ES Module format, or when a CommonJS project is trying to run in an environment configured for ESM without proper interop.
  fix If consuming `ms-rest` from an ESM context, you may need to use dynamic `import('ms-rest')` or ensure your build system handles CommonJS interoperability. If `ms-rest` is requiring another package that is now ESM-only, you might need to find a CommonJS-compatible version of that dependency or upgrade `ms-rest` if a newer, ESM-compatible version exists (though `ms-rest` itself is deprecated).

• A required property was not provided for type 'MyType'. Property name: 'requiredField'.

  cause `ms-rest` performs validation during serialization and deserialization based on the provided mappers. This error indicates a required property, as defined in the mapper, was missing from the object being processed.
  fix Ensure that all properties marked `required: true` in your mapper definitions are present in the JavaScript/TypeScript object you are serializing or deserializing. Check the input object and your mapper definition for consistency.

Warnings

• breaking The entire `azure-sdk-for-node` repository, which includes `ms-rest`, has been deprecated. Users are strongly encouraged to migrate to the new, modular `@azure/*` packages within the `Azure SDK for JavaScript` repository.
  Fix: Migrate to the equivalent services and functionalities provided by the modern `@azure/*` packages. For authentication, use `@azure/identity`. For HTTP pipeline, refer to `@azure/core-rest-pipeline` and `@azure/core-http`.
• breaking The related `ms-rest-js` (isomorphic runtime) experienced breaking changes in its v2.0.0 release, notably changing the default HTTP client from `axios` to `node-fetch` and altering `AbortController` behavior. While `ms-rest` is Node.js-specific, this indicates a pattern of significant API shifts across major versions within the broader `ms-rest` family.
  Fix: Carefully review the changelog for specific breaking changes if upgrading within the 2.x range, particularly for HTTP client behavior or request cancellation. Consider migrating to the modern `@azure/core-http` or `@azure/core-rest-pipeline` for up-to-date and consistent HTTP client abstractions.
• deprecated Authentication mechanisms previously handled by `ms-rest-azure` (which depends on `ms-rest`) and `@azure/ms-rest-nodeauth` are deprecated. Modern Azure SDKs use `@azure/identity` for a unified authentication experience.
  Fix: Replace legacy authentication code that leverages `ms-rest-azure` or `@azure/ms-rest-nodeauth` with credential types and methods provided by `@azure/identity`.
• gotcha Attempting to mix CommonJS `require()` (used by `ms-rest` itself) with ES Modules `import` in a single project can lead to interoperability issues, especially in older Node.js environments or complex module graphs.
  Fix: Ensure consistent module syntax within your project. If using `ms-rest` in a modern ESM project, dynamic `import()` might be required, or configure your build system to correctly transpile/bundle CommonJS modules for ESM consumption. Consider `"type": "module"` in `package.json` for ESM projects or using `.cjs` for CommonJS files within an ESM project.

Install

• npm install ms-rest npm
• yarn add ms-rest yarn
• pnpm add ms-rest pnpm

Imports

• serialize
  wrong:

  const msRest = require('ms-rest'); const serialized = msRest.serialize(...);

  correct:

  import { serialize } from 'ms-rest';

  While CommonJS `require` is common for older Node.js projects using ms-rest, ESM `import` is supported for TypeScript and modern JavaScript environments.
• deserialize
  wrong:

  const msRest = require('ms-rest'); const deserialized = msRest.deserialize(...);

  correct:

  import { deserialize } from 'ms-rest';

  For `deserialize` operations, ensure the mapper definition accurately reflects the expected structure of the incoming data to avoid runtime type errors.
• ServiceClient
  wrong:

  const ServiceClient = require('ms-rest').ServiceClient;

  correct:

  import { ServiceClient } from 'ms-rest';

  ServiceClient is the base class for AutoRest-generated clients, extending it is more common than direct instantiation.

Quickstart

Demonstrates basic object serialization and deserialization using `ms-rest` mappers, including handling required properties during validation.

import { serialize, deserialize } from 'ms-rest';

interface Product {
  id: number;
  name: string;
  price?: number;
}

const productMapper = {
  type: {
    name: 'Composite',
    className: 'Product',
    modelProperties: {
      id: {
        required: true,
        serializedName: 'id',
        type: { name: 'Number' }
      },
      name: {
        required: true,
        serializedName: 'productName',
        type: { name: 'String' }
      },
      price: {
        required: false,
        serializedName: 'productPrice',
        type: { name: 'Number' }
      }
    }
  }
};

const originalProduct: Product = { id: 1, name: 'Example Widget', price: 99.99 };

// Serialize an object based on the defined mapper
const serializedProduct = serialize(productMapper, originalProduct, 'productObject');

console.log('Original Product:', originalProduct);
console.log('Serialized Product:', JSON.stringify(serializedProduct, null, 2));

// Assuming the serialized form might have different property names on the wire
const receivedSerializedProduct = { id: 1, productName: 'Example Widget', productPrice: 99.99 };

// Deserialize the received object back into the Product interface
const deserializedProduct = deserialize(productMapper, receivedSerializedProduct, 'productObject') as Product;

console.log('Deserialized Product:', deserializedProduct);

// Example with missing required property (will throw an error during serialization/deserialization)
try {
  const invalidProduct = { name: 'Missing ID' };
  serialize(productMapper, invalidProduct, 'invalidProduct');
} catch (error: any) {
  console.error('\nError during serialization (expected):', error.message);
}