@xrmforge/helpers 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XrmForge Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,396 @@
+/**
+ * @xrmforge/helpers - Web API Helper Functions
+ *
+ * Lightweight utility functions for building OData query strings
+ * with type-safe field names from generated Fields enums.
+ *
+ * Zero runtime overhead when used with const enums (values are inlined).
+ *
+ * @example
+ * ```typescript
+ * import { select } from '@xrmforge/helpers';
+ *
+ * Xrm.WebApi.retrieveRecord(ref.entityType, ref.id, select(
+ *   AccountFields.Name,
+ *   AccountFields.WebsiteUrl,
+ *   AccountFields.Address1Line1,
+ * ));
+ * ```
+ */
+/**
+ * Build an OData $select query string from field names.
+ *
+ * @param fields - Field names (use generated Fields enum for type safety)
+ * @returns OData query string (e.g. "?$select=name,websiteurl,address1_line1")
+ */
+declare function select(...fields: string[]): string;
+/**
+ * Parse a lookup field from a Dataverse Web API response into a LookupValue.
+ *
+ * Dataverse returns lookups as `_fieldname_value` with OData annotations:
+ * - `_fieldname_value` (GUID)
+ * - `_fieldname_value@OData.Community.Display.V1.FormattedValue` (display name)
+ * - `_fieldname_value@Microsoft.Dynamics.CRM.lookuplogicalname` (entity type)
+ *
+ * This function extracts all three into an `Xrm.LookupValue` object.
+ *
+ * @param response - The raw Web API response object
+ * @param navigationProperty - Navigation property name (use NavigationProperties enum for type safety)
+ * @returns Xrm.LookupValue or null if the lookup is empty
+ *
+ * @example
+ * ```typescript
+ * // With NavigationProperties enum (recommended):
+ * parseLookup(result, AccountNav.Country);
+ *
+ * // Or with navigation property name directly:
+ * parseLookup(result, 'markant_address1_countryid');
+ * ```
+ */
+declare function parseLookup(response: Record<string, unknown>, navigationProperty: string): {
+    id: string;
+    name: string;
+    entityType: string;
+} | null;
+/**
+ * Parse multiple lookup fields from a Dataverse Web API response at once.
+ *
+ * @param response - The raw Web API response object
+ * @param navigationProperties - Navigation property names to parse
+ * @returns Map of navigation property name to LookupValue (null entries omitted)
+ *
+ * @example
+ * ```typescript
+ * const lookups = parseLookups(result, ['markant_address1_countryid', 'parentaccountid']);
+ * formContext.getAttribute(Fields.Country).setValue(
+ *   lookups.markant_address1_countryid ? [lookups.markant_address1_countryid] : null
+ * );
+ * ```
+ */
+declare function parseLookups(response: Record<string, unknown>, navigationProperties: string[]): Record<string, {
+    id: string;
+    name: string;
+    entityType: string;
+} | null>;
+/**
+ * Get the formatted (display) value of any field from a Web API response.
+ *
+ * Works for OptionSets, Lookups, DateTimes, Money, and other formatted fields.
+ *
+ * @param response - The raw Web API response object
+ * @param fieldName - The field logical name (e.g. "statecode", "createdon")
+ * @returns The formatted string value, or null if not available
+ *
+ * @example
+ * ```typescript
+ * const status = parseFormattedValue(result, 'statecode');
+ * // "Active" (instead of 0)
+ * ```
+ */
+declare function parseFormattedValue(response: Record<string, unknown>, fieldName: string): string | null;
+/**
+ * Build an OData $select and $expand query string.
+ *
+ * @param fields - Field names to select
+ * @param expand - Navigation property to expand (optional)
+ * @returns OData query string
+ *
+ * @example
+ * ```typescript
+ * Xrm.WebApi.retrieveRecord("account", id, selectExpand(
+ *   [AccountFields.Name, AccountFields.WebsiteUrl],
+ *   "primarycontactid($select=fullname,emailaddress1)"
+ * ));
+ * ```
+ */
+declare function selectExpand(fields: string[], expand: string): string;
+
+/**
+ * @xrmforge/helpers - Xrm API Constants
+ *
+ * Const enums for all common Xrm string/number constants.
+ * Eliminates raw strings in D365 form scripts.
+ *
+ * @types/xrm defines these as string literal types for compile-time checking,
+ * but does NOT provide runtime constants (XrmEnum is not available at runtime).
+ * These const enums are erased at compile time (zero runtime overhead).
+ *
+ * @example
+ * ```typescript
+ * import { DisplayState } from '@xrmforge/helpers';
+ *
+ * if (tab.getDisplayState() === DisplayState.Expanded) { ... }
+ * ```
+ */
+/** Tab/Section display state */
+declare const enum DisplayState {
+    Expanded = "expanded",
+    Collapsed = "collapsed"
+}
+/** Form notification level (formContext.ui.setFormNotification) */
+declare const enum FormNotificationLevel {
+    Error = "ERROR",
+    Warning = "WARNING",
+    Info = "INFO"
+}
+/** Attribute required level (attribute.setRequiredLevel) */
+declare const enum RequiredLevel {
+    None = "none",
+    Required = "required",
+    Recommended = "recommended"
+}
+/** Attribute submit mode (attribute.setSubmitMode) */
+declare const enum SubmitMode {
+    Always = "always",
+    Never = "never",
+    Dirty = "dirty"
+}
+/** Save mode (eventArgs.getSaveMode()) */
+declare const enum SaveMode {
+    Save = 1,
+    SaveAndClose = 2,
+    Deactivate = 5,
+    Reactivate = 6,
+    Send = 7,
+    Disqualify = 15,
+    Qualify = 16,
+    Assign = 47,
+    SaveAsCompleted = 58,
+    SaveAndNew = 59,
+    AutoSave = 70
+}
+/** Client type (Xrm.Utility.getGlobalContext().client.getClient()) */
+declare const enum ClientType {
+    Web = "Web",
+    Outlook = "Outlook",
+    Mobile = "Mobile"
+}
+/** Client state (Xrm.Utility.getGlobalContext().client.getClientState()) */
+declare const enum ClientState {
+    Online = "Online",
+    Offline = "Offline"
+}
+/** Operation type for Xrm.WebApi.execute getMetadata().operationType */
+declare const enum OperationType {
+    /** Custom Action or OOB Action (POST) */
+    Action = 0,
+    /** Custom Function or OOB Function (GET) */
+    Function = 1,
+    /** CRUD operation (Create, Retrieve, Update, Delete) */
+    CRUD = 2
+}
+/** Structural property for getMetadata().parameterTypes[].structuralProperty */
+declare const enum StructuralProperty {
+    Unknown = 0,
+    PrimitiveType = 1,
+    ComplexType = 2,
+    EnumerationType = 3,
+    Collection = 4,
+    EntityType = 5
+}
+/** Binding type for Custom API definitions */
+declare const enum BindingType {
+    /** Not bound to an entity (globally callable) */
+    Global = 0,
+    /** Bound to a single entity record */
+    Entity = 1,
+    /** Bound to an entity collection */
+    EntityCollection = 2
+}
+
+/**
+ * @xrmforge/helpers - Action/Function Runtime Helpers
+ *
+ * Factory functions for type-safe Custom API execution.
+ * These are imported by generated action/function modules.
+ *
+ * Design:
+ * - `createBoundAction` / `createUnboundAction`: Produce executor objects
+ *   with `.execute()` (calls Xrm.WebApi) and `.request()` (for executeMultiple)
+ * - `executeRequest`: Central execute wrapper (single place for the `as any` cast)
+ * - `withProgress`: Convenience wrapper with progress indicator + error dialog
+ *
+ * @example
+ * ```typescript
+ * // Generated code (in generated/actions/quote.ts):
+ * import { createBoundAction } from '@xrmforge/helpers';
+ * export const WinQuote = createBoundAction('markant_winquote', 'quote');
+ *
+ * // Developer code (in quote-form.ts):
+ * import { WinQuote } from '../generated/actions/quote';
+ * const response = await WinQuote.execute(recordId);
+ * ```
+ */
+/** Parameter metadata for getMetadata().parameterTypes */
+interface ParameterMeta {
+    typeName: string;
+    structuralProperty: number;
+}
+/** Map of parameter names to their OData metadata */
+type ParameterMetaMap = Record<string, ParameterMeta>;
+/** Executor for a bound action without additional parameters */
+interface BoundActionExecutor {
+    execute(recordId: string): Promise<Response>;
+    request(recordId: string): Record<string, unknown>;
+}
+/** Executor for a bound action with typed parameters */
+interface BoundActionWithParamsExecutor<TParams> {
+    execute(recordId: string, params: TParams): Promise<Response>;
+    request(recordId: string, params: TParams): Record<string, unknown>;
+}
+/** Executor for an unbound action without parameters */
+interface UnboundActionExecutor {
+    execute(): Promise<Response>;
+    request(): Record<string, unknown>;
+}
+/** Executor for an unbound action with typed parameters and optional typed response */
+interface UnboundActionWithParamsExecutor<TParams, TResult = void> {
+    execute(params: TParams): Promise<TResult extends void ? Response : TResult>;
+    request(params: TParams): Record<string, unknown>;
+}
+/** Executor for an unbound function with typed response */
+interface UnboundFunctionExecutor<TResult> {
+    execute(): Promise<TResult>;
+    request(): Record<string, unknown>;
+}
+/** Executor for a bound function with typed response */
+interface BoundFunctionExecutor<TResult> {
+    execute(recordId: string): Promise<TResult>;
+    request(recordId: string): Record<string, unknown>;
+}
+/**
+ * Execute a single request via Xrm.WebApi.online.execute().
+ *
+ * This is the ONLY place in the entire framework where the `as any` cast happens.
+ * All generated executors call this function internally.
+ */
+declare function executeRequest(request: Record<string, unknown>): Promise<Response>;
+/**
+ * Execute multiple requests via Xrm.WebApi.online.executeMultiple().
+ *
+ * @param requests - Array of request objects (from `.request()` factories).
+ *   Wrap a subset in an inner array for transactional changeset execution.
+ */
+declare function executeMultiple(requests: Array<Record<string, unknown> | Array<Record<string, unknown>>>): Promise<Response[]>;
+/**
+ * Create an executor for a bound action (entity-bound).
+ *
+ * @param operationName - Custom API unique name (e.g. "markant_winquote")
+ * @param entityLogicalName - Entity logical name (e.g. "quote")
+ */
+declare function createBoundAction(operationName: string, entityLogicalName: string): BoundActionExecutor;
+/**
+ * Create an executor for a bound action with typed parameters.
+ *
+ * @param operationName - Custom API unique name
+ * @param entityLogicalName - Entity logical name
+ * @param paramMeta - Parameter metadata map (parameter name to OData type info)
+ */
+declare function createBoundAction<TParams extends Record<string, unknown>>(operationName: string, entityLogicalName: string, paramMeta: ParameterMetaMap): BoundActionWithParamsExecutor<TParams>;
+/**
+ * Create an executor for an unbound (global) action without parameters.
+ *
+ * @param operationName - Custom API unique name
+ */
+declare function createUnboundAction(operationName: string): UnboundActionExecutor;
+/**
+ * Create an executor for an unbound action with typed parameters and response.
+ *
+ * @param operationName - Custom API unique name
+ * @param paramMeta - Parameter metadata map
+ */
+declare function createUnboundAction<TParams extends Record<string, unknown>, TResult = void>(operationName: string, paramMeta: ParameterMetaMap): UnboundActionWithParamsExecutor<TParams, TResult>;
+/**
+ * Create an executor for an unbound (global) function with typed response.
+ *
+ * @param operationName - Function name (e.g. "WhoAmI")
+ */
+declare function createUnboundFunction<TResult>(operationName: string): UnboundFunctionExecutor<TResult>;
+/**
+ * Create an executor for a bound function with typed response.
+ *
+ * @param operationName - Function name
+ * @param entityLogicalName - Entity logical name
+ */
+declare function createBoundFunction<TResult>(operationName: string, entityLogicalName: string): BoundFunctionExecutor<TResult>;
+/**
+ * Execute an async operation with Xrm progress indicator.
+ *
+ * Shows a progress spinner before the operation, closes it after,
+ * and shows an error dialog on failure.
+ *
+ * @param message - Progress indicator message (e.g. "Processing quote...")
+ * @param operation - Async function to execute
+ * @returns The result of the operation
+ *
+ * @example
+ * ```typescript
+ * await withProgress('Processing quote...', () => WinQuote.execute(recordId));
+ * ```
+ */
+declare function withProgress<T>(message: string, operation: () => Promise<T>): Promise<T>;
+
+/**
+ * @xrmforge/helpers - TypedForm Proxy
+ *
+ * Creates a proxy around Xrm.FormContext that allows direct property access
+ * to form fields. Instead of formContext.getAttribute("name").setValue("X"),
+ * write form.name.setValue("X").
+ *
+ * @example
+ * ```typescript
+ * import { typedForm } from '@xrmforge/helpers';
+ *
+ * type LeadForm = XrmForge.Forms.Lead.LeadMarkantLeadForm;
+ *
+ * const form = typedForm<LeadForm>(formContext);
+ * form.companyname.setValue("Contoso");       // StringAttribute
+ * form.parentaccountid.getValue();             // LookupValue[] | null
+ * form.$context.ui.setFormNotification(...);   // Full FormContext access
+ * form.$control("companyname").setDisabled(true);
+ * ```
+ */
+/**
+ * Extracts the Fields union type from a generated Form interface.
+ * Works with the XrmForge-generated pattern:
+ *   getAttribute<K extends Fields>(name: K): AttrMap[K]
+ *
+ * For overloaded getAttribute, TypeScript resolves to the last overload.
+ * Our generated interfaces have the generic overload first, so we use
+ * a mapped approach with the AttrMap instead.
+ */
+type FormFields<TForm> = TForm extends {
+    getAttribute(name: infer K): unknown;
+} ? K extends string ? K : string : string;
+/**
+ * TypedForm: proxy type that maps field names to their attribute types.
+ *
+ * Since extracting Fields + AttrMap from overloaded getAttribute is unreliable
+ * in TypeScript, we use a two-parameter approach internally but expose a
+ * single-parameter API via a helper type generated by typegen (FormTypedInfo).
+ *
+ * For v0.1.0 we support both signatures:
+ *   typedForm<TForm>(fc)                    -- works when TForm has proper generic getAttribute
+ *   typedForm<TForm, TFields, TAttrMap>(fc) -- explicit, always works
+ */
+type TypedForm<_TForm, TFields extends string = string, TAttrMap extends Record<string, Xrm.Attributes.Attribute> = Record<string, Xrm.Attributes.Attribute>> = {
+    readonly [K in TFields]: K extends keyof TAttrMap ? TAttrMap[K] : Xrm.Attributes.Attribute;
+} & {
+    /** Access the underlying FormContext for ui, data, tabs, etc. */
+    readonly $context: Xrm.FormContext;
+    /** Access a control by field name */
+    $control(name: TFields): Xrm.Controls.Control;
+};
+/**
+ * Create a typed form proxy around a FormContext.
+ *
+ * The proxy intercepts property access and delegates to getAttribute().
+ * Special properties $context and $control provide access to the full
+ * FormContext and controls respectively.
+ *
+ * @param formContext - The Xrm.FormContext from executionContext.getFormContext()
+ * @returns A proxy with direct property access to form fields
+ */
+declare function typedForm<TForm, TFields extends string = string, TAttrMap extends Record<string, Xrm.Attributes.Attribute> = Record<string, Xrm.Attributes.Attribute>>(formContext: Xrm.FormContext): TypedForm<TForm, TFields, TAttrMap>;
+
+export { BindingType, type BoundActionExecutor, type BoundActionWithParamsExecutor, type BoundFunctionExecutor, ClientState, ClientType, DisplayState, type FormFields, FormNotificationLevel, OperationType, type ParameterMeta, type ParameterMetaMap, RequiredLevel, SaveMode, StructuralProperty, SubmitMode, type TypedForm, type UnboundActionExecutor, type UnboundActionWithParamsExecutor, type UnboundFunctionExecutor, createBoundAction, createBoundFunction, createUnboundAction, createUnboundFunction, executeMultiple, executeRequest, parseFormattedValue, parseLookup, parseLookups, select, selectExpand, typedForm, withProgress };

package/dist/index.js

@@ -0,0 +1,329 @@
+// src/webapi-helpers.ts
+function select(...fields) {
+  if (fields.length === 0) return "";
+  return `?$select=${fields.join(",")}`;
+}
+function parseLookup(response, navigationProperty) {
+  const key = `_${navigationProperty}_value`;
+  const id = response[key];
+  if (!id) return null;
+  return {
+    id,
+    name: response[`${key}@OData.Community.Display.V1.FormattedValue`] ?? "",
+    entityType: response[`${key}@Microsoft.Dynamics.CRM.lookuplogicalname`] ?? ""
+  };
+}
+function parseLookups(response, navigationProperties) {
+  const result = {};
+  for (const prop of navigationProperties) {
+    result[prop] = parseLookup(response, prop);
+  }
+  return result;
+}
+function parseFormattedValue(response, fieldName) {
+  return response[`${fieldName}@OData.Community.Display.V1.FormattedValue`] ?? null;
+}
+function selectExpand(fields, expand) {
+  const parts = [];
+  if (fields.length > 0) parts.push(`$select=${fields.join(",")}`);
+  if (expand) parts.push(`$expand=${expand}`);
+  return parts.length > 0 ? `?${parts.join("&")}` : "";
+}
+
+// src/xrm-constants.ts
+var DisplayState = /* @__PURE__ */ ((DisplayState2) => {
+  DisplayState2["Expanded"] = "expanded";
+  DisplayState2["Collapsed"] = "collapsed";
+  return DisplayState2;
+})(DisplayState || {});
+var FormNotificationLevel = /* @__PURE__ */ ((FormNotificationLevel2) => {
+  FormNotificationLevel2["Error"] = "ERROR";
+  FormNotificationLevel2["Warning"] = "WARNING";
+  FormNotificationLevel2["Info"] = "INFO";
+  return FormNotificationLevel2;
+})(FormNotificationLevel || {});
+var RequiredLevel = /* @__PURE__ */ ((RequiredLevel2) => {
+  RequiredLevel2["None"] = "none";
+  RequiredLevel2["Required"] = "required";
+  RequiredLevel2["Recommended"] = "recommended";
+  return RequiredLevel2;
+})(RequiredLevel || {});
+var SubmitMode = /* @__PURE__ */ ((SubmitMode2) => {
+  SubmitMode2["Always"] = "always";
+  SubmitMode2["Never"] = "never";
+  SubmitMode2["Dirty"] = "dirty";
+  return SubmitMode2;
+})(SubmitMode || {});
+var SaveMode = /* @__PURE__ */ ((SaveMode2) => {
+  SaveMode2[SaveMode2["Save"] = 1] = "Save";
+  SaveMode2[SaveMode2["SaveAndClose"] = 2] = "SaveAndClose";
+  SaveMode2[SaveMode2["Deactivate"] = 5] = "Deactivate";
+  SaveMode2[SaveMode2["Reactivate"] = 6] = "Reactivate";
+  SaveMode2[SaveMode2["Send"] = 7] = "Send";
+  SaveMode2[SaveMode2["Disqualify"] = 15] = "Disqualify";
+  SaveMode2[SaveMode2["Qualify"] = 16] = "Qualify";
+  SaveMode2[SaveMode2["Assign"] = 47] = "Assign";
+  SaveMode2[SaveMode2["SaveAsCompleted"] = 58] = "SaveAsCompleted";
+  SaveMode2[SaveMode2["SaveAndNew"] = 59] = "SaveAndNew";
+  SaveMode2[SaveMode2["AutoSave"] = 70] = "AutoSave";
+  return SaveMode2;
+})(SaveMode || {});
+var ClientType = /* @__PURE__ */ ((ClientType2) => {
+  ClientType2["Web"] = "Web";
+  ClientType2["Outlook"] = "Outlook";
+  ClientType2["Mobile"] = "Mobile";
+  return ClientType2;
+})(ClientType || {});
+var ClientState = /* @__PURE__ */ ((ClientState2) => {
+  ClientState2["Online"] = "Online";
+  ClientState2["Offline"] = "Offline";
+  return ClientState2;
+})(ClientState || {});
+var OperationType = /* @__PURE__ */ ((OperationType2) => {
+  OperationType2[OperationType2["Action"] = 0] = "Action";
+  OperationType2[OperationType2["Function"] = 1] = "Function";
+  OperationType2[OperationType2["CRUD"] = 2] = "CRUD";
+  return OperationType2;
+})(OperationType || {});
+var StructuralProperty = /* @__PURE__ */ ((StructuralProperty2) => {
+  StructuralProperty2[StructuralProperty2["Unknown"] = 0] = "Unknown";
+  StructuralProperty2[StructuralProperty2["PrimitiveType"] = 1] = "PrimitiveType";
+  StructuralProperty2[StructuralProperty2["ComplexType"] = 2] = "ComplexType";
+  StructuralProperty2[StructuralProperty2["EnumerationType"] = 3] = "EnumerationType";
+  StructuralProperty2[StructuralProperty2["Collection"] = 4] = "Collection";
+  StructuralProperty2[StructuralProperty2["EntityType"] = 5] = "EntityType";
+  return StructuralProperty2;
+})(StructuralProperty || {});
+var BindingType = /* @__PURE__ */ ((BindingType2) => {
+  BindingType2[BindingType2["Global"] = 0] = "Global";
+  BindingType2[BindingType2["Entity"] = 1] = "Entity";
+  BindingType2[BindingType2["EntityCollection"] = 2] = "EntityCollection";
+  return BindingType2;
+})(BindingType || {});
+
+// src/action-runtime.ts
+function executeRequest(request) {
+  return Xrm.WebApi.online.execute(request);
+}
+function executeMultiple(requests) {
+  return Xrm.WebApi.online.executeMultiple(requests);
+}
+function cleanRecordId(id) {
+  return id.replace(/[{}]/g, "");
+}
+function buildBoundRequest(operationName, entityLogicalName, operationType, recordId, paramMeta, params) {
+  const parameterTypes = {
+    entity: {
+      typeName: `mscrm.${entityLogicalName}`,
+      structuralProperty: 5 /* EntityType */
+    }
+  };
+  if (paramMeta) {
+    for (const [key, meta] of Object.entries(paramMeta)) {
+      parameterTypes[key] = meta;
+    }
+  }
+  const request = {
+    getMetadata: () => ({
+      boundParameter: "entity",
+      parameterTypes,
+      operationName,
+      operationType
+    }),
+    entity: {
+      id: cleanRecordId(recordId),
+      entityType: entityLogicalName
+    }
+  };
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      request[key] = value;
+    }
+  }
+  return request;
+}
+function buildUnboundRequest(operationName, operationType, paramMeta, params) {
+  const parameterTypes = {};
+  if (paramMeta) {
+    for (const [key, meta] of Object.entries(paramMeta)) {
+      parameterTypes[key] = meta;
+    }
+  }
+  const request = {
+    getMetadata: () => ({
+      boundParameter: null,
+      parameterTypes,
+      operationName,
+      operationType
+    })
+  };
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      request[key] = value;
+    }
+  }
+  return request;
+}
+function createBoundAction(operationName, entityLogicalName, paramMeta) {
+  return {
+    execute(recordId, params) {
+      const req = buildBoundRequest(
+        operationName,
+        entityLogicalName,
+        0 /* Action */,
+        recordId,
+        paramMeta,
+        params
+      );
+      return executeRequest(req);
+    },
+    request(recordId, params) {
+      return buildBoundRequest(
+        operationName,
+        entityLogicalName,
+        0 /* Action */,
+        recordId,
+        paramMeta,
+        params
+      );
+    }
+  };
+}
+function createUnboundAction(operationName, paramMeta) {
+  return {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- return type varies (Response or parsed JSON)
+    async execute(params) {
+      const req = buildUnboundRequest(
+        operationName,
+        0 /* Action */,
+        paramMeta,
+        params
+      );
+      const response = await executeRequest(req);
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(errorText);
+      }
+      if (response.status !== 204) {
+        return response.json();
+      }
+      return response;
+    },
+    request(params) {
+      return buildUnboundRequest(
+        operationName,
+        0 /* Action */,
+        paramMeta,
+        params
+      );
+    }
+  };
+}
+function createUnboundFunction(operationName) {
+  return {
+    async execute() {
+      const req = buildUnboundRequest(operationName, 1 /* Function */);
+      const response = await executeRequest(req);
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(errorText);
+      }
+      return response.json();
+    },
+    request() {
+      return buildUnboundRequest(operationName, 1 /* Function */);
+    }
+  };
+}
+function createBoundFunction(operationName, entityLogicalName) {
+  return {
+    async execute(recordId) {
+      const req = buildBoundRequest(
+        operationName,
+        entityLogicalName,
+        1 /* Function */,
+        recordId
+      );
+      const response = await executeRequest(req);
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(errorText);
+      }
+      return response.json();
+    },
+    request(recordId) {
+      return buildBoundRequest(
+        operationName,
+        entityLogicalName,
+        1 /* Function */,
+        recordId
+      );
+    }
+  };
+}
+async function withProgress(message, operation) {
+  Xrm.Utility.showProgressIndicator(message);
+  try {
+    return await operation();
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    Xrm.Navigation.openErrorDialog({ message: msg });
+    throw error;
+  } finally {
+    Xrm.Utility.closeProgressIndicator();
+  }
+}
+
+// src/typed-form.ts
+function typedForm(formContext) {
+  return new Proxy(formContext, {
+    get(_target, prop) {
+      if (typeof prop !== "string") {
+        return formContext[prop];
+      }
+      if (prop === "$context") return formContext;
+      if (prop === "$control") {
+        return (name) => formContext.getControl(name);
+      }
+      const attr = formContext.getAttribute(prop);
+      if (attr) return attr;
+      return formContext[prop];
+    },
+    set(_target, prop, _value) {
+      throw new TypeError(
+        `Cannot assign to '${String(prop)}'. Use form.${String(prop)}.setValue() instead.`
+      );
+    },
+    has(_target, prop) {
+      if (typeof prop !== "string") return false;
+      if (prop === "$context" || prop === "$control") return true;
+      return formContext.getAttribute(prop) !== null;
+    }
+  });
+}
+export {
+  BindingType,
+  ClientState,
+  ClientType,
+  DisplayState,
+  FormNotificationLevel,
+  OperationType,
+  RequiredLevel,
+  SaveMode,
+  StructuralProperty,
+  SubmitMode,
+  createBoundAction,
+  createBoundFunction,
+  createUnboundAction,
+  createUnboundFunction,
+  executeMultiple,
+  executeRequest,
+  parseFormattedValue,
+  parseLookup,
+  parseLookups,
+  select,
+  selectExpand,
+  typedForm,
+  withProgress
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/webapi-helpers.ts","../src/xrm-constants.ts","../src/action-runtime.ts","../src/typed-form.ts"],"sourcesContent":["/**\n * @xrmforge/helpers - Web API Helper Functions\n *\n * Lightweight utility functions for building OData query strings\n * with type-safe field names from generated Fields enums.\n *\n * Zero runtime overhead when used with const enums (values are inlined).\n *\n * @example\n * ```typescript\n * import { select } from '@xrmforge/helpers';\n *\n * Xrm.WebApi.retrieveRecord(ref.entityType, ref.id, select(\n *   AccountFields.Name,\n *   AccountFields.WebsiteUrl,\n *   AccountFields.Address1Line1,\n * ));\n * ```\n */\n\n/**\n * Build an OData $select query string from field names.\n *\n * @param fields - Field names (use generated Fields enum for type safety)\n * @returns OData query string (e.g. \"?$select=name,websiteurl,address1_line1\")\n */\nexport function select(...fields: string[]): string {\n  if (fields.length === 0) return '';\n  return `?$select=${fields.join(',')}`;\n}\n\n/**\n * Parse a lookup field from a Dataverse Web API response into a LookupValue.\n *\n * Dataverse returns lookups as `_fieldname_value` with OData annotations:\n * - `_fieldname_value` (GUID)\n * - `_fieldname_value@OData.Community.Display.V1.FormattedValue` (display name)\n * - `_fieldname_value@Microsoft.Dynamics.CRM.lookuplogicalname` (entity type)\n *\n * This function extracts all three into an `Xrm.LookupValue` object.\n *\n * @param response - The raw Web API response object\n * @param navigationProperty - Navigation property name (use NavigationProperties enum for type safety)\n * @returns Xrm.LookupValue or null if the lookup is empty\n *\n * @example\n * ```typescript\n * // With NavigationProperties enum (recommended):\n * parseLookup(result, AccountNav.Country);\n *\n * // Or with navigation property name directly:\n * parseLookup(result, 'markant_address1_countryid');\n * ```\n */\nexport function parseLookup(\n  response: Record<string, unknown>,\n  navigationProperty: string,\n): { id: string; name: string; entityType: string } | null {\n  const key = `_${navigationProperty}_value`;\n  const id = response[key] as string | undefined;\n  if (!id) return null;\n\n  return {\n    id,\n    name: (response[`${key}@OData.Community.Display.V1.FormattedValue`] as string) ?? '',\n    entityType: (response[`${key}@Microsoft.Dynamics.CRM.lookuplogicalname`] as string) ?? '',\n  };\n}\n\n/**\n * Parse multiple lookup fields from a Dataverse Web API response at once.\n *\n * @param response - The raw Web API response object\n * @param navigationProperties - Navigation property names to parse\n * @returns Map of navigation property name to LookupValue (null entries omitted)\n *\n * @example\n * ```typescript\n * const lookups = parseLookups(result, ['markant_address1_countryid', 'parentaccountid']);\n * formContext.getAttribute(Fields.Country).setValue(\n *   lookups.markant_address1_countryid ? [lookups.markant_address1_countryid] : null\n * );\n * ```\n */\nexport function parseLookups(\n  response: Record<string, unknown>,\n  navigationProperties: string[],\n): Record<string, { id: string; name: string; entityType: string } | null> {\n  const result: Record<string, { id: string; name: string; entityType: string } | null> = {};\n  for (const prop of navigationProperties) {\n    result[prop] = parseLookup(response, prop);\n  }\n  return result;\n}\n\n/**\n * Get the formatted (display) value of any field from a Web API response.\n *\n * Works for OptionSets, Lookups, DateTimes, Money, and other formatted fields.\n *\n * @param response - The raw Web API response object\n * @param fieldName - The field logical name (e.g. \"statecode\", \"createdon\")\n * @returns The formatted string value, or null if not available\n *\n * @example\n * ```typescript\n * const status = parseFormattedValue(result, 'statecode');\n * // \"Active\" (instead of 0)\n * ```\n */\nexport function parseFormattedValue(\n  response: Record<string, unknown>,\n  fieldName: string,\n): string | null {\n  return (response[`${fieldName}@OData.Community.Display.V1.FormattedValue`] as string) ?? null;\n}\n\n/**\n * Build an OData $select and $expand query string.\n *\n * @param fields - Field names to select\n * @param expand - Navigation property to expand (optional)\n * @returns OData query string\n *\n * @example\n * ```typescript\n * Xrm.WebApi.retrieveRecord(\"account\", id, selectExpand(\n *   [AccountFields.Name, AccountFields.WebsiteUrl],\n *   \"primarycontactid($select=fullname,emailaddress1)\"\n * ));\n * ```\n */\nexport function selectExpand(fields: string[], expand: string): string {\n  const parts: string[] = [];\n  if (fields.length > 0) parts.push(`$select=${fields.join(',')}`);\n  if (expand) parts.push(`$expand=${expand}`);\n  return parts.length > 0 ? `?${parts.join('&')}` : '';\n}\n","/**\n * @xrmforge/helpers - Xrm API Constants\n *\n * Const enums for all common Xrm string/number constants.\n * Eliminates raw strings in D365 form scripts.\n *\n * @types/xrm defines these as string literal types for compile-time checking,\n * but does NOT provide runtime constants (XrmEnum is not available at runtime).\n * These const enums are erased at compile time (zero runtime overhead).\n *\n * @example\n * ```typescript\n * import { DisplayState } from '@xrmforge/helpers';\n *\n * if (tab.getDisplayState() === DisplayState.Expanded) { ... }\n * ```\n */\n\n/** Tab/Section display state */\nexport const enum DisplayState {\n  Expanded = 'expanded',\n  Collapsed = 'collapsed',\n}\n\n// FormType: use XrmEnum.FormType from @types/xrm (already defined as const enum there)\n\n/** Form notification level (formContext.ui.setFormNotification) */\nexport const enum FormNotificationLevel {\n  Error = 'ERROR',\n  Warning = 'WARNING',\n  Info = 'INFO',\n}\n\n/** Attribute required level (attribute.setRequiredLevel) */\nexport const enum RequiredLevel {\n  None = 'none',\n  Required = 'required',\n  Recommended = 'recommended',\n}\n\n/** Attribute submit mode (attribute.setSubmitMode) */\nexport const enum SubmitMode {\n  Always = 'always',\n  Never = 'never',\n  Dirty = 'dirty',\n}\n\n/** Save mode (eventArgs.getSaveMode()) */\nexport const enum SaveMode {\n  Save = 1,\n  SaveAndClose = 2,\n  Deactivate = 5,\n  Reactivate = 6,\n  Send = 7,\n  Disqualify = 15,\n  Qualify = 16,\n  Assign = 47,\n  SaveAsCompleted = 58,\n  SaveAndNew = 59,\n  AutoSave = 70,\n}\n\n/** Client type (Xrm.Utility.getGlobalContext().client.getClient()) */\nexport const enum ClientType {\n  Web = 'Web',\n  Outlook = 'Outlook',\n  Mobile = 'Mobile',\n}\n\n/** Client state (Xrm.Utility.getGlobalContext().client.getClientState()) */\nexport const enum ClientState {\n  Online = 'Online',\n  Offline = 'Offline',\n}\n\n// WebApi Execute Constants\n\n/** Operation type for Xrm.WebApi.execute getMetadata().operationType */\nexport const enum OperationType {\n  /** Custom Action or OOB Action (POST) */\n  Action = 0,\n  /** Custom Function or OOB Function (GET) */\n  Function = 1,\n  /** CRUD operation (Create, Retrieve, Update, Delete) */\n  CRUD = 2,\n}\n\n/** Structural property for getMetadata().parameterTypes[].structuralProperty */\nexport const enum StructuralProperty {\n  Unknown = 0,\n  PrimitiveType = 1,\n  ComplexType = 2,\n  EnumerationType = 3,\n  Collection = 4,\n  EntityType = 5,\n}\n\n/** Binding type for Custom API definitions */\nexport const enum BindingType {\n  /** Not bound to an entity (globally callable) */\n  Global = 0,\n  /** Bound to a single entity record */\n  Entity = 1,\n  /** Bound to an entity collection */\n  EntityCollection = 2,\n}\n","/**\n * @xrmforge/helpers - Action/Function Runtime Helpers\n *\n * Factory functions for type-safe Custom API execution.\n * These are imported by generated action/function modules.\n *\n * Design:\n * - `createBoundAction` / `createUnboundAction`: Produce executor objects\n *   with `.execute()` (calls Xrm.WebApi) and `.request()` (for executeMultiple)\n * - `executeRequest`: Central execute wrapper (single place for the `as any` cast)\n * - `withProgress`: Convenience wrapper with progress indicator + error dialog\n *\n * @example\n * ```typescript\n * // Generated code (in generated/actions/quote.ts):\n * import { createBoundAction } from '@xrmforge/helpers';\n * export const WinQuote = createBoundAction('markant_winquote', 'quote');\n *\n * // Developer code (in quote-form.ts):\n * import { WinQuote } from '../generated/actions/quote';\n * const response = await WinQuote.execute(recordId);\n * ```\n */\n\nimport { OperationType, StructuralProperty } from './xrm-constants.js';\n\n// Types\n\n/** Parameter metadata for getMetadata().parameterTypes */\nexport interface ParameterMeta {\n  typeName: string;\n  structuralProperty: number;\n}\n\n/** Map of parameter names to their OData metadata */\nexport type ParameterMetaMap = Record<string, ParameterMeta>;\n\n/** Executor for a bound action without additional parameters */\nexport interface BoundActionExecutor {\n  execute(recordId: string): Promise<Response>;\n  request(recordId: string): Record<string, unknown>;\n}\n\n/** Executor for a bound action with typed parameters */\nexport interface BoundActionWithParamsExecutor<TParams> {\n  execute(recordId: string, params: TParams): Promise<Response>;\n  request(recordId: string, params: TParams): Record<string, unknown>;\n}\n\n/** Executor for an unbound action without parameters */\nexport interface UnboundActionExecutor {\n  execute(): Promise<Response>;\n  request(): Record<string, unknown>;\n}\n\n/** Executor for an unbound action with typed parameters and optional typed response */\nexport interface UnboundActionWithParamsExecutor<TParams, TResult = void> {\n  execute(params: TParams): Promise<TResult extends void ? Response : TResult>;\n  request(params: TParams): Record<string, unknown>;\n}\n\n/** Executor for an unbound function with typed response */\nexport interface UnboundFunctionExecutor<TResult> {\n  execute(): Promise<TResult>;\n  request(): Record<string, unknown>;\n}\n\n/** Executor for a bound function with typed response */\nexport interface BoundFunctionExecutor<TResult> {\n  execute(recordId: string): Promise<TResult>;\n  request(recordId: string): Record<string, unknown>;\n}\n\n// Central Execute\n\n/**\n * Execute a single request via Xrm.WebApi.online.execute().\n *\n * This is the ONLY place in the entire framework where the `as any` cast happens.\n * All generated executors call this function internally.\n */\nexport function executeRequest(request: Record<string, unknown>): Promise<Response> {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return (Xrm.WebApi as any).online.execute(request) as Promise<Response>;\n}\n\n/**\n * Execute multiple requests via Xrm.WebApi.online.executeMultiple().\n *\n * @param requests - Array of request objects (from `.request()` factories).\n *   Wrap a subset in an inner array for transactional changeset execution.\n */\nexport function executeMultiple(\n  requests: Array<Record<string, unknown> | Array<Record<string, unknown>>>,\n): Promise<Response[]> {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return (Xrm.WebApi as any).online.executeMultiple(requests) as Promise<Response[]>;\n}\n\n// Request Builder (internal)\n\nfunction cleanRecordId(id: string): string {\n  return id.replace(/[{}]/g, '');\n}\n\nfunction buildBoundRequest(\n  operationName: string,\n  entityLogicalName: string,\n  operationType: OperationType,\n  recordId: string,\n  paramMeta?: ParameterMetaMap,\n  params?: Record<string, unknown>,\n): Record<string, unknown> {\n  const parameterTypes: Record<string, ParameterMeta> = {\n    entity: {\n      typeName: `mscrm.${entityLogicalName}`,\n      structuralProperty: StructuralProperty.EntityType,\n    },\n  };\n\n  if (paramMeta) {\n    for (const [key, meta] of Object.entries(paramMeta)) {\n      parameterTypes[key] = meta;\n    }\n  }\n\n  const request: Record<string, unknown> = {\n    getMetadata: () => ({\n      boundParameter: 'entity',\n      parameterTypes,\n      operationName,\n      operationType,\n    }),\n    entity: {\n      id: cleanRecordId(recordId),\n      entityType: entityLogicalName,\n    },\n  };\n\n  if (params) {\n    for (const [key, value] of Object.entries(params)) {\n      request[key] = value;\n    }\n  }\n\n  return request;\n}\n\nfunction buildUnboundRequest(\n  operationName: string,\n  operationType: OperationType,\n  paramMeta?: ParameterMetaMap,\n  params?: Record<string, unknown>,\n): Record<string, unknown> {\n  const parameterTypes: Record<string, ParameterMeta> = {};\n\n  if (paramMeta) {\n    for (const [key, meta] of Object.entries(paramMeta)) {\n      parameterTypes[key] = meta;\n    }\n  }\n\n  const request: Record<string, unknown> = {\n    getMetadata: () => ({\n      boundParameter: null,\n      parameterTypes,\n      operationName,\n      operationType,\n    }),\n  };\n\n  if (params) {\n    for (const [key, value] of Object.entries(params)) {\n      request[key] = value;\n    }\n  }\n\n  return request;\n}\n\n// Action Factories\n\n/**\n * Create an executor for a bound action (entity-bound).\n *\n * @param operationName - Custom API unique name (e.g. \"markant_winquote\")\n * @param entityLogicalName - Entity logical name (e.g. \"quote\")\n */\nexport function createBoundAction(\n  operationName: string,\n  entityLogicalName: string,\n): BoundActionExecutor;\n\n/**\n * Create an executor for a bound action with typed parameters.\n *\n * @param operationName - Custom API unique name\n * @param entityLogicalName - Entity logical name\n * @param paramMeta - Parameter metadata map (parameter name to OData type info)\n */\nexport function createBoundAction<TParams extends Record<string, unknown>>(\n  operationName: string,\n  entityLogicalName: string,\n  paramMeta: ParameterMetaMap,\n): BoundActionWithParamsExecutor<TParams>;\n\nexport function createBoundAction<TParams extends Record<string, unknown>>(\n  operationName: string,\n  entityLogicalName: string,\n  paramMeta?: ParameterMetaMap,\n): BoundActionExecutor | BoundActionWithParamsExecutor<TParams> {\n  return {\n    execute(recordId: string, params?: TParams): Promise<Response> {\n      const req = buildBoundRequest(\n        operationName, entityLogicalName, OperationType.Action,\n        recordId, paramMeta, params,\n      );\n      return executeRequest(req);\n    },\n    request(recordId: string, params?: TParams): Record<string, unknown> {\n      return buildBoundRequest(\n        operationName, entityLogicalName, OperationType.Action,\n        recordId, paramMeta, params,\n      );\n    },\n  };\n}\n\n/**\n * Create an executor for an unbound (global) action without parameters.\n *\n * @param operationName - Custom API unique name\n */\nexport function createUnboundAction(\n  operationName: string,\n): UnboundActionExecutor;\n\n/**\n * Create an executor for an unbound action with typed parameters and response.\n *\n * @param operationName - Custom API unique name\n * @param paramMeta - Parameter metadata map\n */\nexport function createUnboundAction<\n  TParams extends Record<string, unknown>,\n  TResult = void,\n>(\n  operationName: string,\n  paramMeta: ParameterMetaMap,\n): UnboundActionWithParamsExecutor<TParams, TResult>;\n\nexport function createUnboundAction<\n  TParams extends Record<string, unknown>,\n  TResult = void,\n>(\n  operationName: string,\n  paramMeta?: ParameterMetaMap,\n): UnboundActionExecutor | UnboundActionWithParamsExecutor<TParams, TResult> {\n  return {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- return type varies (Response or parsed JSON)\n    async execute(params?: TParams): Promise<any> {\n      const req = buildUnboundRequest(\n        operationName, OperationType.Action, paramMeta, params,\n      );\n      const response = await executeRequest(req);\n      if (!response.ok) {\n        const errorText = await response.text();\n        throw new Error(errorText);\n      }\n      if (response.status !== 204) {\n        return response.json();\n      }\n      return response;\n    },\n    request(params?: TParams): Record<string, unknown> {\n      return buildUnboundRequest(\n        operationName, OperationType.Action, paramMeta, params,\n      );\n    },\n  };\n}\n\n// Function Factories\n\n/**\n * Create an executor for an unbound (global) function with typed response.\n *\n * @param operationName - Function name (e.g. \"WhoAmI\")\n */\nexport function createUnboundFunction<TResult>(\n  operationName: string,\n): UnboundFunctionExecutor<TResult> {\n  return {\n    async execute(): Promise<TResult> {\n      const req = buildUnboundRequest(operationName, OperationType.Function);\n      const response = await executeRequest(req);\n      if (!response.ok) {\n        const errorText = await response.text();\n        throw new Error(errorText);\n      }\n      return response.json() as Promise<TResult>;\n    },\n    request(): Record<string, unknown> {\n      return buildUnboundRequest(operationName, OperationType.Function);\n    },\n  };\n}\n\n/**\n * Create an executor for a bound function with typed response.\n *\n * @param operationName - Function name\n * @param entityLogicalName - Entity logical name\n */\nexport function createBoundFunction<TResult>(\n  operationName: string,\n  entityLogicalName: string,\n): BoundFunctionExecutor<TResult> {\n  return {\n    async execute(recordId: string): Promise<TResult> {\n      const req = buildBoundRequest(\n        operationName, entityLogicalName, OperationType.Function, recordId,\n      );\n      const response = await executeRequest(req);\n      if (!response.ok) {\n        const errorText = await response.text();\n        throw new Error(errorText);\n      }\n      return response.json() as Promise<TResult>;\n    },\n    request(recordId: string): Record<string, unknown> {\n      return buildBoundRequest(\n        operationName, entityLogicalName, OperationType.Function, recordId,\n      );\n    },\n  };\n}\n\n// Convenience\n\n/**\n * Execute an async operation with Xrm progress indicator.\n *\n * Shows a progress spinner before the operation, closes it after,\n * and shows an error dialog on failure.\n *\n * @param message - Progress indicator message (e.g. \"Processing quote...\")\n * @param operation - Async function to execute\n * @returns The result of the operation\n *\n * @example\n * ```typescript\n * await withProgress('Processing quote...', () => WinQuote.execute(recordId));\n * ```\n */\nexport async function withProgress<T>(\n  message: string,\n  operation: () => Promise<T>,\n): Promise<T> {\n  Xrm.Utility.showProgressIndicator(message);\n  try {\n    return await operation();\n  } catch (error: unknown) {\n    const msg = error instanceof Error ? error.message : String(error);\n    Xrm.Navigation.openErrorDialog({ message: msg });\n    throw error;\n  } finally {\n    Xrm.Utility.closeProgressIndicator();\n  }\n}\n","/**\n * @xrmforge/helpers - TypedForm Proxy\n *\n * Creates a proxy around Xrm.FormContext that allows direct property access\n * to form fields. Instead of formContext.getAttribute(\"name\").setValue(\"X\"),\n * write form.name.setValue(\"X\").\n *\n * @example\n * ```typescript\n * import { typedForm } from '@xrmforge/helpers';\n *\n * type LeadForm = XrmForge.Forms.Lead.LeadMarkantLeadForm;\n *\n * const form = typedForm<LeadForm>(formContext);\n * form.companyname.setValue(\"Contoso\");       // StringAttribute\n * form.parentaccountid.getValue();             // LookupValue[] | null\n * form.$context.ui.setFormNotification(...);   // Full FormContext access\n * form.$control(\"companyname\").setDisabled(true);\n * ```\n */\n\n/**\n * Extracts the Fields union type from a generated Form interface.\n * Works with the XrmForge-generated pattern:\n *   getAttribute<K extends Fields>(name: K): AttrMap[K]\n *\n * For overloaded getAttribute, TypeScript resolves to the last overload.\n * Our generated interfaces have the generic overload first, so we use\n * a mapped approach with the AttrMap instead.\n */\nexport type FormFields<TForm> = TForm extends {\n  getAttribute(name: infer K): unknown;\n} ? K extends string ? K : string : string;\n\n/**\n * TypedForm: proxy type that maps field names to their attribute types.\n *\n * Since extracting Fields + AttrMap from overloaded getAttribute is unreliable\n * in TypeScript, we use a two-parameter approach internally but expose a\n * single-parameter API via a helper type generated by typegen (FormTypedInfo).\n *\n * For v0.1.0 we support both signatures:\n *   typedForm<TForm>(fc)                    -- works when TForm has proper generic getAttribute\n *   typedForm<TForm, TFields, TAttrMap>(fc) -- explicit, always works\n */\nexport type TypedForm<\n  _TForm,\n  TFields extends string = string,\n  TAttrMap extends Record<string, Xrm.Attributes.Attribute> = Record<string, Xrm.Attributes.Attribute>,\n> = {\n  readonly [K in TFields]: K extends keyof TAttrMap\n    ? TAttrMap[K]\n    : Xrm.Attributes.Attribute;\n} & {\n  /** Access the underlying FormContext for ui, data, tabs, etc. */\n  readonly $context: Xrm.FormContext;\n  /** Access a control by field name */\n  $control(name: TFields): Xrm.Controls.Control;\n};\n\n/**\n * Create a typed form proxy around a FormContext.\n *\n * The proxy intercepts property access and delegates to getAttribute().\n * Special properties $context and $control provide access to the full\n * FormContext and controls respectively.\n *\n * @param formContext - The Xrm.FormContext from executionContext.getFormContext()\n * @returns A proxy with direct property access to form fields\n */\nexport function typedForm<\n  TForm,\n  TFields extends string = string,\n  TAttrMap extends Record<string, Xrm.Attributes.Attribute> = Record<string, Xrm.Attributes.Attribute>,\n>(formContext: Xrm.FormContext): TypedForm<TForm, TFields, TAttrMap> {\n  return new Proxy(formContext as unknown as TypedForm<TForm, TFields, TAttrMap>, {\n    get(_target, prop) {\n      // Symbols and non-string keys: delegate to formContext\n      if (typeof prop !== 'string') {\n        return (formContext as unknown as Record<symbol, unknown>)[prop];\n      }\n      if (prop === '$context') return formContext;\n      if (prop === '$control') {\n        return (name: string) => formContext.getControl(name);\n      }\n      // Try getAttribute first (form field access)\n      const attr = formContext.getAttribute(prop);\n      if (attr) return attr;\n      // Fallback to FormContext properties (data, ui, etc.)\n      return (formContext as unknown as Record<string, unknown>)[prop];\n    },\n\n    set(_target, prop, _value) {\n      throw new TypeError(\n        `Cannot assign to '${String(prop)}'. Use form.${String(prop)}.setValue() instead.`,\n      );\n    },\n\n    has(_target, prop) {\n      if (typeof prop !== 'string') return false;\n      if (prop === '$context' || prop === '$control') return true;\n      return formContext.getAttribute(prop) !== null;\n    },\n  });\n}\n"],"mappings":"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","names":["DisplayState","FormNotificationLevel","RequiredLevel","SubmitMode","SaveMode","ClientType","ClientState","OperationType","StructuralProperty","BindingType"]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@xrmforge/helpers",
+  "version": "0.1.0",
+  "description": "Browser-safe runtime helpers for Dynamics 365 form scripts: select(), parseLookup(), typedForm(), Xrm constants, Action/Function executors",
+  "keywords": [
+    "dynamics-365",
+    "typescript",
+    "xrm",
+    "dataverse",
+    "web-resources",
+    "helpers"
+  ],
+  "license": "MIT",
+  "author": "XrmForge Contributors",
+  "homepage": "https://github.com/juergenbeck/XrmForge/tree/main/packages/helpers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/juergenbeck/XrmForge.git",
+    "directory": "packages/helpers"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@types/xrm": ">=9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "clean": "rm -rf dist"
+  }
+}