@mohsinonxrm/dataverse-sdk-entities-runtime

Runtime base classes and interfaces for generated Dataverse entity types. This package provides the foundational types and helpers that code generated by @mohsinonxrm/dataverse-sdk-generator depends on.

📦 Installation

pnpm add @mohsinonxrm/dataverse-sdk-entities-runtime

🎯 Purpose

This package serves as the runtime foundation for early-bound entity types generated from Dataverse metadata. It provides:

• Base interfaces (IEntity, EntityReference)
• Metadata structures (EntityMetadata, AttributeMetadata, NavigationMetadata)
• Type guards (isEntity, isEntityReference)
• Helper functions for URL construction, entity formatting, etc.

Note: You typically don't use this package directly. Instead, use @mohsinonxrm/dataverse-sdk-generator to generate strongly-typed entity classes that reference these base types.

📚 Core Types

IEntity

Base interface for all Dataverse entities. Generated entity interfaces extend this.

import type { IEntity } from "@mohsinonxrm/dataverse-sdk-entities-runtime";

const account: IEntity = {
  logicalName: "account",
  id: "123e4567-e89b-12d3-a456-426614174000",
  name: "Contoso",
  creditlimit: 50000,
};

EntityReference

Represents a reference to another entity record (for lookups).

import {
  createEntityReference,
  type EntityReference,
} from "@mohsinonxrm/dataverse-sdk-entities-runtime";

const contactRef: EntityReference = createEntityReference(
  "contact",
  "456e7890-e89b-12d3-a456-426614174000",
  "Jane Doe"
);

EntityMetadata

Complete metadata descriptor for a Dataverse entity type.

import type { EntityMetadata } from "@mohsinonxrm/dataverse-sdk-entities-runtime";

const accountMetadata: EntityMetadata = {
  typeName: "Microsoft.Dynamics.CRM.account",
  logicalName: "account",
  collectionName: "accounts",
  primaryIdAttribute: "accountid",
  primaryNameAttribute: "name",
  attributeTypes: {
    accountid: "Guid",
    name: "String",
    creditlimit: "Money",
  },
  navigation: {
    primarycontactid: {
      name: "primarycontactid",
      targetType: "contact",
      isCollection: false,
      relationshipName: "account_primary_contact",
    },
  },
};

🛠️ Helper Functions

Type Guards

import { isEntity, isEntityReference } from "@mohsinonxrm/dataverse-sdk-entities-runtime";

if (isEntity(value)) {
  console.log("Entity:", value.logicalName);
}

if (isEntityReference(value)) {
  console.log("Reference to:", value.logicalName, value.id);
}

URL Construction

import { getCollectionUrl, getEntityUrl } from "@mohsinonxrm/dataverse-sdk-entities-runtime";

const baseUrl = "https://org.crm.dynamics.com/api/data/v9.2";

// Get collection URL
const accountsUrl = getCollectionUrl(accountMetadata, baseUrl);
// → "https://org.crm.dynamics.com/api/data/v9.2/accounts"

// Get single entity URL
const accountUrl = getEntityUrl(accountMetadata, "123-guid", baseUrl);
// → "https://org.crm.dynamics.com/api/data/v9.2/accounts(123-guid)"

Entity Formatting for Create/Update

import { formatEntityForWrite } from "@mohsinonxrm/dataverse-sdk-entities-runtime";

const entity: Partial<IEntity> = {
  logicalName: "account",
  name: "Contoso",
  creditlimit: 50000,
};

const payload = formatEntityForWrite(entity, accountMetadata);
// {
//   '@odata.type': 'Microsoft.Dynamics.CRM.account',
//   'name': 'Contoso',
//   'creditlimit': 50000
// }

🔧 Base Classes for Generated Code

ActionBase<TResponse>

Abstract base class for generated action classes.

import { ActionBase } from "@mohsinonxrm/dataverse-sdk-entities-runtime";

class CustomAction extends ActionBase<{ Result: string }> {
  toRequestInformation(baseUrl: string) {
    return {
      method: "POST",
      url: `${baseUrl}/CustomAction`,
      headers: { "Content-Type": "application/json" },
      body: { Parameter: "value" },
    };
  }

  async parseResponse(response: Response) {
    const data = await response.json();
    return { Result: data.Result };
  }
}

FunctionBase<TResponse>

Abstract base class for generated function classes.

import { FunctionBase } from "@mohsinonxrm/dataverse-sdk-entities-runtime";

class CustomFunction extends FunctionBase<{ Count: number }> {
  toRequestInformation(baseUrl: string) {
    return {
      method: "GET",
      url: `${baseUrl}/CustomFunction(Name=@Name)`,
      headers: {},
      query: { "@Name": "value" },
    };
  }

  async parseResponse(response: Response) {
    const data = await response.json();
    return { Count: data.Count };
  }
}

📖 Generated Entity Example

Here's what generated entity code looks like:

// Generated by @mohsinonxrm/dataverse-sdk-generator

import type { IEntity, EntityMetadata } from "@mohsinonxrm/dataverse-sdk-entities-runtime";
import type { Contact } from "./Contact.js";

export interface Account extends IEntity {
  accountid?: string;
  name?: string;
  creditlimit?: number;
  primarycontactid?: Contact;
}

export const AccountMetadata: EntityMetadata = {
  typeName: "Microsoft.Dynamics.CRM.account",
  logicalName: "account",
  collectionName: "accounts",
  primaryIdAttribute: "accountid",
  primaryNameAttribute: "name",
  attributeTypes: {
    accountid: "Guid",
    name: "String",
    creditlimit: "Money",
  },
  navigation: {
    primarycontactid: {
      name: "primarycontactid",
      targetType: "contact",
      isCollection: false,
      relationshipName: "account_primary_contact",
    },
  },
};

🔗 Usage with Generator

1. Install the generator:

   pnpm add -D @mohsinonxrm/dataverse-sdk-generator

2. Initialize configuration:

   pnpm dataverse-gen init

3. Generate entity types:

   pnpm dataverse-gen generate

4. Use generated types:

   import { Account, AccountMetadata } from "./generated/entities/Account.js";
   import { DataverseClient } from "@mohsinonxrm/dataverse-sdk-core";
   
   const client = new DataverseClient({
     /* ... */
   });
   
   // Type-safe entity operations
   const account: Account = {
     logicalName: "account",
     name: "Contoso",
     creditlimit: 50000,
   };
   
   await client.api("/accounts").post(account);

📜 License

GNU AGPL v3.0 — see LICENSE

🤝 Related Packages

• @mohsinonxrm/dataverse-sdk-generator — Generate early-bound entity types
• @mohsinonxrm/dataverse-sdk-core — Core SDK client
• @mohsinonxrm/dataverse-sdk-metadata — Metadata operations