@xrmforge/typegen 0.4.0 → 0.5.1

package/MIGRATION.md

@@ -0,0 +1,154 @@
+# XrmForge Migration Guide
+
+How to convert legacy Dynamics 365 JavaScript to type-safe TypeScript with XrmForge.
+
+## Step 1: Initialize Project
+
+```bash
+npx @xrmforge/cli init my-project --prefix contoso
+cd my-project
+npm install
+```
+
+## Step 2: Generate Types from Dataverse
+
+```bash
+npx xrmforge generate \
+  --url https://YOUR-ORG.crm4.dynamics.com \
+  --auth interactive \
+  --tenant-id YOUR-TENANT-ID \
+  --client-id YOUR-CLIENT-ID \
+  --entities account,contact,opportunity \
+  --output ./typings
+```
+
+This generates:
+- `typings/entities/*.d.ts` - Entity interfaces with typed attributes
+- `typings/forms/*.d.ts` - Form interfaces with Fields enum, Tabs enum, Subgrid enum
+- `typings/optionsets/*.d.ts` - OptionSet const enums with labels
+- `typings/entity-names.d.ts` - EntityNames const enum
+
+## Step 3: Convert Form Scripts
+
+### Before (legacy JavaScript):
+
+```javascript
+// account.js - global functions, raw strings, no type safety
+var LM = LM || {};
+LM.Account = {
+  onLoad: function(executionContext) {
+    var formContext = executionContext.getFormContext();
+    var name = formContext.getAttribute("name");           // generic Attribute
+    var status = formContext.getAttribute("statuscode");
+    if (status.getValue() === 1) {                         // magic number!
+      formContext.getControl("revenue").setVisible(true);
+    }
+  }
+};
+```
+
+### After (XrmForge TypeScript):
+
+```typescript
+// account-form.ts - typed, safe, autocomplete everywhere
+import { AccountMainFormFieldsEnum as Fields } from '../../typings/forms/account';
+
+export function onLoad(executionContext: Xrm.Events.EventContext): void {
+  const form = executionContext.getFormContext() as XrmForge.Forms.Account.AccountMainForm;
+
+  // Fields enum: compile error on typos, autocomplete in IDE
+  const name = form.getAttribute(Fields.AccountName);  // StringAttribute, not generic
+  const status = form.getAttribute(Fields.StatusCode);  // OptionSetAttribute
+
+  // OptionSet enum: no magic numbers
+  if (status.getValue() === XrmForge.OptionSets.Account.StatusCode.Active) {
+    form.getControl(Fields.Revenue).setVisible(true);
+  }
+}
+```
+
+### Key Differences:
+
+| Legacy | XrmForge |
+|--------|----------|
+| `getAttribute("name")` | `getAttribute(Fields.AccountName)` |
+| `getValue() === 1` | `getValue() === OptionSets.StatusCode.Active` |
+| `formContext` (untyped) | `form as AccountMainForm` (typed) |
+| `getControl("revenue")` | `getControl(Fields.Revenue)` |
+| No compile-time checks | Typos are compile errors |
+
+## Step 4: Replace Common Patterns
+
+### Lookup Values
+
+```typescript
+// Before:
+var value = formContext.getAttribute("primarycontactid").getValue();
+var id = value[0].id.replace("{","").replace("}","");
+
+// After: use parseLookup from @xrmforge/typegen
+import { parseLookup } from '@xrmforge/typegen';
+const contact = parseLookup(form.getAttribute(Fields.PrimaryContactId));
+if (contact) {
+  console.log(contact.id);  // already clean GUID
+}
+```
+
+### Web API Queries
+
+```typescript
+// Before:
+Xrm.WebApi.retrieveMultipleRecords("account",
+  "?$select=name,revenue&$filter=statecode eq 0");
+
+// After: use Fields enum for $select
+import { select } from '@xrmforge/typegen';
+import { AccountFields } from '../../typings/entities/account';
+Xrm.WebApi.retrieveMultipleRecords("account",
+  `?$select=${select(AccountFields.Name, AccountFields.Revenue)}&$filter=statecode eq 0`);
+```
+
+### Form Testing
+
+```typescript
+// Before: no tests, or complex manual mocks
+
+// After: @xrmforge/testing
+import { createFormMock, fireOnChange } from '@xrmforge/testing';
+import type { AccountMainForm, AccountMainFormMockValues } from '../../typings/forms/account';
+
+const mock = createFormMock<AccountMainForm, AccountMainFormMockValues>({
+  name: 'Contoso Ltd',
+  revenue: 1000000,
+  statuscode: 1,
+});
+
+onLoad(mock.executionContext);
+expect(mock.formContext.getControl('revenue').getVisible()).toBe(true);
+```
+
+## Step 5: Build
+
+```bash
+npx xrmforge build          # IIFE bundles for D365
+npx xrmforge build --watch  # Watch mode
+```
+
+## Step 6: Replace Magic Numbers
+
+Search your code for patterns like:
+- `getValue() === 123` or `getValue() !== 456`
+- `setValue("statuscode", 1)`
+- Raw OptionSet values in if/switch statements
+
+Replace with generated const enums from `typings/optionsets/`.
+
+## Checklist
+
+- [ ] All `getAttribute("string")` calls use Fields enum
+- [ ] All OptionSet comparisons use const enums (no magic numbers)
+- [ ] All `Xrm.Page` calls replaced with `formContext`
+- [ ] Form scripts export functions (not global namespace objects)
+- [ ] Each form script has tests using `@xrmforge/testing`
+- [ ] `xrmforge build` produces IIFE bundles
+- [ ] `tsc --noEmit` passes with zero errors

package/dist/index.d.ts

@@ -330,16 +330,6 @@ declare class DataverseHttpClient {
      * @param signal - Optional AbortSignal to cancel the request
      */
     getAll<T>(path: string, signal?: AbortSignal): Promise<T[]>;
-    /**
-     * Execute a POST request that is semantically a read operation.
-     * Used for Dataverse actions like RetrieveMetadataChanges that require POST
-     * but do not modify data. Allowed even in read-only mode.
-     *
-     * @param path - API path (relative to apiUrl)
-     * @param body - JSON body to send
-     * @param signal - Optional AbortSignal to cancel the request
-     */
-    postReadOnly<T>(path: string, body: unknown, signal?: AbortSignal): Promise<T>;
     /**
      * Returns true if this client is in read-only mode (the safe default).
      */

package/dist/index.js

@@ -404,28 +404,6 @@ var DataverseHttpClient = class {
     }
     return allResults;
   }
-  /**
-   * Execute a POST request that is semantically a read operation.
-   * Used for Dataverse actions like RetrieveMetadataChanges that require POST
-   * but do not modify data. Allowed even in read-only mode.
-   *
-   * @param path - API path (relative to apiUrl)
-   * @param body - JSON body to send
-   * @param signal - Optional AbortSignal to cancel the request
-   */
-  async postReadOnly(path2, body, signal) {
-    const ALLOWED_PATHS = ["/RetrieveMetadataChanges"];
-    const normalizedPath = path2.startsWith("/") ? path2 : `/${path2}`;
-    if (!ALLOWED_PATHS.some((p) => normalizedPath.startsWith(p))) {
-      throw new ApiRequestError(
-        "API_2001" /* API_REQUEST_FAILED */,
-        `postReadOnly is only allowed for safe read operations: ${ALLOWED_PATHS.join(", ")}. Got: "${normalizedPath}"`,
-        { path: normalizedPath }
-      );
-    }
-    const url = this.resolveUrl(path2);
-    return this.executeWithConcurrency(url, signal, "POST", body);
-  }
   // ─── Read-Only Enforcement ─────────────────────────────────────────────
   /**
    * Returns true if this client is in read-only mode (the safe default).
@@ -514,12 +492,14 @@ var DataverseHttpClient = class {
     try {
       tokenResponse = await this.credential.getToken(scope);
     } catch (error) {
+      const cause = error instanceof Error ? error.message : String(error);
       throw new AuthenticationError(
         "AUTH_1003" /* AUTH_TOKEN_FAILED */,
-        `Failed to acquire access token for ${this.baseUrl}. Verify your authentication configuration.`,
+        `Failed to acquire access token for ${this.baseUrl}. Verify your authentication configuration.
+Cause: ${cause}`,
         {
           environmentUrl: this.baseUrl,
-          originalError: error instanceof Error ? error.message : String(error)
+          originalError: cause
         }
       );
     }
@@ -1421,26 +1401,22 @@ var ChangeDetector = class {
    */
   async detectChanges(clientVersionStamp) {
     log6.info("Detecting metadata changes since last run");
-    const requestBody = {
-      Query: {
-        Criteria: {
-          FilterOperator: "And",
-          Conditions: []
-        },
-        Properties: {
-          AllProperties: false,
-          PropertyNames: ["LogicalName"]
-        }
+    const query = {
+      Criteria: {
+        FilterOperator: "And",
+        Conditions: []
       },
-      ClientVersionStamp: clientVersionStamp,
-      DeletedMetadataFilters: "Entity"
+      Properties: {
+        AllProperties: false,
+        PropertyNames: ["LogicalName"]
+      }
     };
+    const queryJson = encodeURIComponent(JSON.stringify(query));
+    const deletedFilter = `Microsoft.Dynamics.CRM.DeletedMetadataFilters'Default'`;
+    const path2 = `/RetrieveMetadataChanges(Query=@q,ClientVersionStamp=@s,DeletedMetadataFilters=@d)?@q=${queryJson}&@s='${clientVersionStamp}'&@d=${deletedFilter}`;
     let response;
     try {
-      response = await this.http.postReadOnly(
-        "/RetrieveMetadataChanges",
-        requestBody
-      );
+      response = await this.http.get(path2);
     } catch (error) {
       if (this.isExpiredVersionStampError(error)) {
         throw new MetadataError(
@@ -1475,22 +1451,19 @@ var ChangeDetector = class {
    */
   async getInitialVersionStamp() {
     log6.info("Fetching initial server version stamp");
-    const requestBody = {
-      Query: {
-        Criteria: {
-          FilterOperator: "And",
-          Conditions: []
-        },
-        Properties: {
-          AllProperties: false,
-          PropertyNames: ["LogicalName"]
-        }
+    const query = {
+      Criteria: {
+        FilterOperator: "And",
+        Conditions: []
+      },
+      Properties: {
+        AllProperties: false,
+        PropertyNames: ["LogicalName"]
       }
     };
-    const response = await this.http.postReadOnly(
-      "/RetrieveMetadataChanges",
-      requestBody
-    );
+    const queryParam = encodeURIComponent(JSON.stringify(query));
+    const path2 = `/RetrieveMetadataChanges(Query=@q)?@q=${queryParam}`;
+    const response = await this.http.get(path2);
     log6.info("Initial version stamp acquired");
     return response.ServerVersionStamp;
   }
@@ -2135,6 +2108,50 @@ function generateFormInterface(form, entityLogicalName, attributeMap, options =
       lines.push("");
     }
   }
+  const specialControls = form.allSpecialControls || [];
+  const subgrids = specialControls.filter((sc) => sc.controlType === "subgrid" || sc.controlType === "editablegrid");
+  const quickViews = specialControls.filter((sc) => sc.controlType === "quickview");
+  if (subgrids.length > 0) {
+    const subgridsEnumName = `${baseName}FormSubgrids`;
+    lines.push(`  /** Subgrid constants for "${form.name}" (compile-time only, zero runtime) */`);
+    lines.push(`  const enum ${subgridsEnumName} {`);
+    const usedMembers = /* @__PURE__ */ new Set();
+    for (const sg of subgrids) {
+      let member = toSafeFormName(sg.id) || toPascalCase(sg.id);
+      const original = member;
+      let counter = 2;
+      while (usedMembers.has(member)) {
+        member = `${original}${counter}`;
+        counter++;
+      }
+      usedMembers.add(member);
+      const label = sg.targetEntityType ? `Subgrid: ${sg.targetEntityType}` : `Subgrid`;
+      lines.push(`    /** ${label} */`);
+      lines.push(`    ${member} = '${sg.id}',`);
+    }
+    lines.push("  }");
+    lines.push("");
+  }
+  if (quickViews.length > 0) {
+    const qvEnumName = `${baseName}FormQuickViews`;
+    lines.push(`  /** Quick View constants for "${form.name}" (compile-time only, zero runtime) */`);
+    lines.push(`  const enum ${qvEnumName} {`);
+    const usedMembers = /* @__PURE__ */ new Set();
+    for (const qv of quickViews) {
+      let member = toSafeFormName(qv.id) || toPascalCase(qv.id);
+      const original = member;
+      let counter = 2;
+      while (usedMembers.has(member)) {
+        member = `${original}${counter}`;
+        counter++;
+      }
+      usedMembers.add(member);
+      lines.push(`    /** Quick View */`);
+      lines.push(`    ${member} = '${qv.id}',`);
+    }
+    lines.push("  }");
+    lines.push("");
+  }
   lines.push(`  /** ${form.name} */`);
   lines.push(`  interface ${interfaceName} extends Omit<Xrm.FormContext, 'getAttribute' | 'getControl'> {`);
   lines.push(`    /** Typisierter Feldzugriff: nur Felder die auf diesem Formular existieren */`);
@@ -2144,7 +2161,6 @@ function generateFormInterface(form, entityLogicalName, attributeMap, options =
   lines.push("");
   lines.push(`    /** Typisierter Control-Zugriff: nur Controls die auf diesem Formular existieren */`);
   lines.push(`    getControl<K extends ${fieldsTypeName}>(name: K): ${ctrlMapName}[K];`);
-  const specialControls = form.allSpecialControls || [];
   for (const sc of specialControls) {
     const xrmType = specialControlToXrmType(sc.controlType);
     if (xrmType) {