@xrmforge/typegen 0.7.1 → 0.8.1

package/MIGRATION.md

@@ -2,6 +2,32 @@
 
 How to convert legacy Dynamics 365 JavaScript to type-safe TypeScript with XrmForge.
 
+## Breaking Changes in v0.8.0 (ES Module Output)
+
+### What changed
+- Generated files are now `.ts` modules with `export` statements instead of `.d.ts` files with `declare namespace`
+- Default output directory changed from `./typings` to `./generated`
+- Entity Fields enums are now generated in a separate `fields/` directory
+- Action declarations and runtime code are now in a single `.ts` file per group
+- The barrel index uses `export * from` instead of `/// <reference path />`
+
+### Migration steps
+1. Update your `xrmforge generate` command: replace `--output ./typings` with `--output ./generated` (or omit for the new default)
+2. Replace namespace access with imports:
+   ```typescript
+   // Before (v0.7.x):
+   type AccountForm = XrmForge.Forms.Account.AccountMainForm;
+
+   // After (v0.8.0):
+   import type { AccountMainForm } from './generated/forms/account.js';
+   ```
+3. Update your tsconfig.json: replace `"typings/**/*.d.ts"` in `include` with `"generated/**/*.ts"`
+4. Entity Fields enums are now available:
+   ```typescript
+   import { AccountFields } from './generated/fields/account.js';
+   const result = await Xrm.WebApi.retrieveRecord('account', id, `?$select=${AccountFields.Name},${AccountFields.Telephone1}`);
+   ```
+
 ## Breaking Changes in v0.7.0
 
 - The `@xrmforge/typegen/helpers` subpath export has been removed.
@@ -30,14 +56,15 @@ npx xrmforge generate \
   --tenant-id YOUR-TENANT-ID \
   --client-id YOUR-CLIENT-ID \
   --entities account,contact,opportunity \
-  --output ./typings
+  --output ./generated
 ```
 
 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
+- `generated/entities/*.ts` - Entity interfaces with typed attributes
+- `generated/forms/*.ts` - Form interfaces with Fields enum, Tabs enum, Subgrid enum
+- `generated/optionsets/*.ts` - OptionSet const enums with labels
+- `generated/fields/*.ts` - Entity Fields enums for type-safe $select queries
+- `generated/entity-names.ts` - EntityNames const enum
 
 ## Step 3: Convert Form Scripts
 
@@ -62,17 +89,19 @@ LM.Account = {
 
 ```typescript
 // account-form.ts - typed, safe, autocomplete everywhere
-import { AccountMainFormFieldsEnum as Fields } from '../../typings/forms/account';
+import { AccountMainFormFieldsEnum as Fields } from '../../generated/forms/account.js';
+import type { AccountMainForm } from '../../generated/forms/account.js';
+import { StatusCode } from '../../generated/optionsets/account.js';
 
 export function onLoad(executionContext: Xrm.Events.EventContext): void {
-  const form = executionContext.getFormContext() as XrmForge.Forms.Account.AccountMainForm;
+  const form = executionContext.getFormContext() as 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) {
+  if (status.getValue() === StatusCode.Active) {
     form.getControl(Fields.Revenue).setVisible(true);
   }
 }
@@ -114,7 +143,7 @@ Xrm.WebApi.retrieveMultipleRecords("account",
 
 // After: use Fields enum for $select
 import { select } from '@xrmforge/helpers';
-import { AccountFields } from '../../typings/entities/account';
+import { AccountFields } from '../../generated/fields/account.js';
 Xrm.WebApi.retrieveMultipleRecords("account",
   `?$select=${select(AccountFields.Name, AccountFields.Revenue)}&$filter=statecode eq 0`);
 ```
@@ -126,7 +155,7 @@ Xrm.WebApi.retrieveMultipleRecords("account",
 
 // After: @xrmforge/testing
 import { createFormMock, fireOnChange } from '@xrmforge/testing';
-import type { AccountMainForm, AccountMainFormMockValues } from '../../typings/forms/account';
+import type { AccountMainForm, AccountMainFormMockValues } from '../../generated/forms/account.js';
 
 const mock = createFormMock<AccountMainForm, AccountMainFormMockValues>({
   name: 'Contoso Ltd',
@@ -152,7 +181,7 @@ Search your code for patterns like:
 - `setValue("statuscode", 1)`
 - Raw OptionSet values in if/switch statements
 
-Replace with generated const enums from `typings/optionsets/`.
+Replace with generated const enums from `generated/optionsets/`.
 
 ## Checklist
 

package/dist/index.d.ts

@@ -1145,10 +1145,9 @@ declare function shouldIncludeInEntityInterface(attr: AttributeMetadata): boolea
  * Generate the ActivityParty base interface declaration.
  * This is a fixed structure (system entity, never customized).
  *
- * @param namespace - Namespace for the interface (default: "XrmForge.Entities")
  * @returns TypeScript declaration string
  */
-declare function generateActivityPartyInterface(namespace?: string): string;
+declare function generateActivityPartyInterface(): string;
 
 /**
  * @xrmforge/typegen - Generator-specific Label Utilities
@@ -1215,8 +1214,6 @@ declare function disambiguateEnumMembers(members: Array<{
 interface EntityGeneratorOptions {
     /** Label configuration for dual-language JSDoc comments */
     labelConfig?: LabelConfig;
-    /** Namespace for generated types (default: "XrmForge.Entities") */
-    namespace?: string;
 }
 /**
  * Generate a TypeScript declaration for an entity interface.
@@ -1249,8 +1246,6 @@ declare function generateEntityInterface(info: EntityTypeInfo, options?: EntityG
 interface OptionSetGeneratorOptions {
     /** Label configuration for dual-language JSDoc comments */
     labelConfig?: LabelConfig;
-    /** Namespace for generated types (default: "XrmForge.OptionSets") */
-    namespace?: string;
 }
 /**
  * Generate a TypeScript const enum declaration from an OptionSet.
@@ -1331,8 +1326,6 @@ declare function generateEntityOptionSets(picklistAttributes: Array<{
 interface FormGeneratorOptions {
     /** Label configuration for dual-language JSDoc comments */
     labelConfig?: LabelConfig;
-    /** Namespace prefix for generated types (default: "XrmForge.Forms") */
-    namespacePrefix?: string;
     /** Form types to include (default: [2] = Main only) */
     formTypes?: number[];
 }
@@ -1384,8 +1377,6 @@ declare function generateEntityForms(forms: ParsedForm[], entityLogicalName: str
 interface EntityFieldsGeneratorOptions {
     /** Label configuration for dual-language JSDoc comments */
     labelConfig?: LabelConfig;
-    /** Namespace for generated enums (default: "XrmForge.Entities") */
-    namespace?: string;
 }
 /**
  * Generate a const enum with all entity fields for Web API usage.
@@ -1439,8 +1430,6 @@ declare function generateEntityNavigationProperties(info: EntityTypeInfo, option
  * ```
  */
 interface EntityNamesGeneratorOptions {
-    /** Namespace (default: "XrmForge") */
-    namespace?: string;
 }
 /**
  * Generate a const enum mapping entity PascalCase names to logical names.
@@ -1449,7 +1438,7 @@ interface EntityNamesGeneratorOptions {
  * @param options - Generator options
  * @returns TypeScript declaration string
  */
-declare function generateEntityNamesEnum(entityNames: string[], options?: EntityNamesGeneratorOptions): string;
+declare function generateEntityNamesEnum(entityNames: string[], _options?: EntityNamesGeneratorOptions): string;
 
 /**
  * @xrmforge/typegen - Web API Helper Functions
@@ -1810,23 +1799,22 @@ declare function withProgress<T>(message: string, operation: () => Promise<T>):
 
 /** Options for action/function generation */
 interface ActionGeneratorOptions {
-    /** Import path for @xrmforge/typegen (default: "@xrmforge/typegen") */
+    /** Import path for @xrmforge/helpers (default: "@xrmforge/helpers") */
     importPath?: string;
-    /** Namespace for generated types (default: "XrmForge.Actions" / "XrmForge.Functions") */
-    actionsNamespace?: string;
-    functionsNamespace?: string;
 }
 /**
- * Generate .d.ts content for a group of Custom APIs.
+ * Generate declarations (interfaces only) for a group of Custom APIs.
+ * Output is flat ES module style with `export interface`.
  *
  * @param apis - Custom APIs to generate (all in the same group: same entity or all global)
- * @param isFunction - true for functions namespace, false for actions
- * @param entityName - Entity name for bound APIs, undefined for global
- * @param options - Generator options
+ * @param isFunction - true for functions, false for actions
+ * @param _entityName - Entity name for bound APIs, undefined for global (reserved for future use)
+ * @param _options - Generator options (reserved for future use)
  */
-declare function generateActionDeclarations(apis: CustomApiTypeInfo[], isFunction: boolean, entityName?: string, options?: ActionGeneratorOptions): string;
+declare function generateActionDeclarations(apis: CustomApiTypeInfo[], _isFunction: boolean, _entityName?: string, _options?: ActionGeneratorOptions): string;
 /**
- * Generate .ts content with runtime executors for a group of Custom APIs.
+ * Generate a single .ts file with both interfaces and runtime executors for a group of Custom APIs.
+ * Combines what was previously split into .d.ts (interfaces) and .ts (executors).
  *
  * @param apis - Custom APIs to generate
  * @param isFunction - true for functions, false for actions
@@ -1905,7 +1893,7 @@ interface GeneratedFile {
     /** File content */
     content: string;
     /** Type of generated content */
-    type: 'entity' | 'optionset' | 'form' | 'action';
+    type: 'entity' | 'optionset' | 'form' | 'action' | 'fields';
 }
 /** Statistics about cache usage during generation */
 interface CacheStats {
@@ -1939,8 +1927,8 @@ interface GenerationResult {
  *
  * Coordinates the full type generation pipeline:
  * 1. Fetch metadata for requested entities (via MetadataClient)
- * 2. Generate entity interfaces, OptionSet enums, form interfaces
- * 3. Write .d.ts files to disk
+ * 2. Generate entity interfaces, OptionSet enums, form interfaces, fields enums
+ * 3. Write .ts files to disk
  *
  * This is the main entry point that ties all components together.
  */
@@ -1953,7 +1941,7 @@ interface GenerationResult {
  * const orchestrator = new TypeGenerationOrchestrator(credential, {
  *   environmentUrl: 'https://myorg.crm4.dynamics.com',
  *   entities: ['account', 'contact'],
- *   outputDir: './typings',
+ *   outputDir: './generated',
  *   labelConfig: { primaryLanguage: 1033, secondaryLanguage: 1031 },
  * });
  * const result = await orchestrator.generate();