@microsoft/agents-hosting-dialogs 0.2.10-g3ac88ff25e → 0.3.5

package/src/memory/dialogPath.ts

@@ -7,27 +7,51 @@
  * Defines path for available dialogs.
  */
 export class DialogPath {
-  /// Counter of emitted events.
-  static readonly eventCounter = 'dialog.eventCounter'
-
-  /// Currently expected properties.
-  static readonly expectedProperties = 'dialog.expectedProperties'
-
-  /// Default operation to use for entities where there is no identified operation entity.
-  static readonly defaultOperation = 'dialog.defaultOperation'
-
-  /// Last surfaced entity ambiguity event.
-  static readonly lastEvent = 'dialog.lastEvent'
-
-  /// Currently required properties.
-  static readonly requiredProperties = 'dialog.requiredProperties'
-
-  /// Number of retries for the current Ask.
-  static readonly retries = 'dialog.retries'
-
-  /// Last intent.
-  static readonly lastIntent = 'dialog.lastIntent'
-
-  /// Last trigger event: defined in FormEvent, ask, clarifyEntity etc..
-  static readonly lastTriggerEvent = 'dialog.lastTriggerEvent'
+  /**
+   * Counter of emitted events.
+   * @constant A string key representing the event counter path (`'dialog.eventCounter'`).
+   */
+  static readonly eventCounter: string = 'dialog.eventCounter'
+
+  /**
+   * Currently expected properties.
+   * @constant A string key representing the expected properties path (`'dialog.expectedProperties'`).
+   */
+  static readonly expectedProperties: string = 'dialog.expectedProperties'
+
+  /**
+   * Default operation to use for entities where there is no identified operation entity.
+   * @constant A string key representing the default operation path (`'dialog.defaultOperation'`).
+   */
+  static readonly defaultOperation: string = 'dialog.defaultOperation'
+
+  /**
+   * Last surfaced entity ambiguity event.
+   * @constant A string key representing the last event path (`'dialog.lastEvent'`).
+   */
+  static readonly lastEvent: string = 'dialog.lastEvent'
+
+  /**
+   * Currently required properties.
+   * @constant A string key representing the required properties path (`'dialog.requiredProperties'`).
+   */
+  static readonly requiredProperties: string = 'dialog.requiredProperties'
+
+  /**
+   * Number of retries for the current Ask.
+   * @constant A string key representing the retries path (`'dialog.retries'`).
+   */
+  static readonly retries: string = 'dialog.retries'
+
+  /**
+   * Last intent.
+   * @constant A string key representing the last intent path (`'dialog.lastIntent'`).
+   */
+  static readonly lastIntent: string = 'dialog.lastIntent'
+
+  /**
+   * Last trigger event: defined in FormEvent, ask, clarifyEntity etc.
+   * @constant A string key representing the last trigger event path (`'dialog.lastTriggerEvent'`).
+   */
+  static readonly lastTriggerEvent: string = 'dialog.lastTriggerEvent'
 }

package/src/memory/dialogStateManager.ts

@@ -435,7 +435,7 @@ export class DialogStateManager {
      * Track when specific paths are changed.
      *
      * @param paths Paths to track.
-     * @returns Normalized paths to pass to [anyPathChanged()](#anypathchanged).
+     * @returns Normalized paths to pass to `anyPathChanged` method.
      */
   trackPaths (paths: string[]): string[] {
     const allPaths: string[] = []
@@ -459,7 +459,7 @@ export class DialogStateManager {
      * Check to see if any path has changed since watermark.
      *
      * @param counter Time counter to compare to.
-     * @param paths Paths from [trackPaths()](#trackpaths) to check.
+     * @param paths Paths from `trackPaths` method to check.
      * @returns True if any path has changed since counter.
      */
   anyPathChanged (counter: number, paths: string[]): boolean {

package/src/memory/pathResolvers/aliasPathResolver.ts

@@ -4,6 +4,10 @@
  */
 import { PathResolver } from './pathResolver'
 
+/**
+ * A class that resolves paths by replacing an alias with a specified prefix and optional postfix.
+ * This is useful for transforming paths that use shorthand aliases into fully qualified paths.
+ */
 export class AliasPathResolver implements PathResolver {
   private readonly alias: string
   private readonly prefix: string

package/src/memory/pathResolvers/atAtPathResolver.ts

@@ -4,10 +4,14 @@
  */
 import { AliasPathResolver } from './aliasPathResolver'
 
+/**
+ * A specialized path resolver that replaces the '@@' alias with the prefix 'turn.recognized.entities.'.
+ * This is used to resolve paths related to recognized entities in a conversational turn.
+ */
 export class AtAtPathResolver extends AliasPathResolver {
   /**
-     * Initializes a new instance of the AtAtPathResolver class.
-     */
+   * Initializes a new instance of the AtAtPathResolver class.
+   */
   constructor () {
     super('@@', 'turn.recognized.entities.')
   }

package/src/memory/pathResolvers/atPathResolver.ts

@@ -4,23 +4,29 @@
  */
 import { AliasPathResolver } from './aliasPathResolver'
 
+/**
+ * A path resolver that replaces the '@' alias with a specific prefix and transforms paths
+ * to access recognized entities in a conversational turn. It ensures that the resolved
+ * path includes the 'first()' function for entity properties.
+ */
 export class AtPathResolver extends AliasPathResolver {
   private readonly _prefix = 'turn.recognized.entities.'
   private readonly _delims = ['.', '[']
 
   /**
-     * Initializes a new instance of the AtPathResolver class.
-     */
+   * Initializes a new instance of the AtPathResolver class.
+   */
   constructor () {
     super('@', '')
   }
 
   /**
-     * Transforms the path.
-     *
-     * @param path Path to inspect.
-     * @returns The transformed path.
-     */
+   * Transforms the path by replacing the '@' alias and appending the 'first()' function
+   * to entity properties.
+   *
+   * @param path The path to inspect and transform.
+   * @returns The transformed path.
+   */
   transformPath (path: string): string {
     path = path.trim()
     if (path.startsWith('@') && path.length > 1 && !path.startsWith('@@')) {

package/src/memory/pathResolvers/dollarPathResolver.ts

@@ -4,10 +4,15 @@
  */
 import { AliasPathResolver } from './aliasPathResolver'
 
+/**
+ * A path resolver that resolves paths starting with a dollar sign ('$')
+ * to the 'dialog.' namespace.
+ */
 export class DollarPathResolver extends AliasPathResolver {
   /**
-     * Initializes a new instance of the DollarPathResolver class.
-     */
+   * Initializes a new instance of the DollarPathResolver class.
+   * This resolver maps paths starting with '$' to the 'dialog.' namespace.
+   */
   constructor () {
     super('$', 'dialog.')
   }

package/src/memory/pathResolvers/hashPathResolver.ts

@@ -4,10 +4,15 @@
  */
 import { AliasPathResolver } from './aliasPathResolver'
 
+/**
+ * A path resolver that resolves paths starting with a hash sign ('#')
+ * to the 'turn.recognized.intents.' namespace.
+ */
 export class HashPathResolver extends AliasPathResolver {
   /**
-     * Initializes a new instance of the HashPathResolver class.
-     */
+   * Initializes a new instance of the HashPathResolver class.
+   * This resolver maps paths starting with '#' to the 'turn.recognized.intents.' namespace.
+   */
   constructor () {
     super('#', 'turn.recognized.intents.')
   }

package/src/memory/pathResolvers/pathResolver.ts

@@ -3,12 +3,17 @@
  * Licensed under the MIT License.
  */
 
+/**
+ * Interface for resolving and transforming paths.
+ * Implementations of this interface define how specific path patterns
+ * should be transformed into other formats or namespaces.
+ */
 export interface PathResolver {
   /**
-     * Transform the path
-     *
-     * @param path Path to inspect.
-     * @returns Transformed path
-     */
+   * Transforms the given path into a new format or namespace.
+   *
+   * @param path - The path to inspect and transform.
+   * @returns The transformed path.
+   */
   transformPath(path: string): string;
 }

package/src/memory/pathResolvers/percentPathResolver.ts

@@ -4,10 +4,15 @@
  */
 import { AliasPathResolver } from './aliasPathResolver'
 
+/**
+ * A path resolver that resolves paths starting with a percent sign ('%')
+ * to the 'class.' namespace.
+ */
 export class PercentPathResolver extends AliasPathResolver {
   /**
-     * Initializes a new instance of the PercentPathResolver class.
-     */
+   * Initializes a new instance of the PercentPathResolver class.
+   * This resolver maps paths starting with '%' to the 'class.' namespace.
+   */
   constructor () {
     super('%', 'class.')
   }

package/src/memory/scopePath.ts

@@ -7,13 +7,48 @@
  * Defines paths for the available scopes.
  */
 export class ScopePath {
+  /**
+   * Path for user-specific data.
+   */
   static readonly user = 'user'
+
+  /**
+   * Path for conversation-specific data.
+   */
   static readonly conversation = 'conversation'
+
+  /**
+   * Path for dialog-specific data.
+   */
   static readonly dialog = 'dialog'
+
+  /**
+   * Path for dialog class-specific data.
+   */
   static readonly dialogClass = 'dialogClass'
+
+  /**
+   * Path for dialog context-specific data.
+   */
   static readonly dialogContext = 'dialogContext'
+
+  /**
+   * Path for the current dialog instance data.
+   */
   static readonly this = 'this'
+
+  /**
+   * Path for class-specific data.
+   */
   static readonly class = 'class'
+
+  /**
+   * Path for settings-specific data.
+   */
   static readonly settings = 'settings'
+
+  /**
+   * Path for turn-specific data.
+   */
   static readonly turn = 'turn'
 }

package/src/memory/scopes/classMemoryScope.ts

@@ -7,22 +7,26 @@ import { ScopePath } from '../scopePath'
 import { DialogContext } from '../../dialogContext'
 import { Dialog } from '../../dialog'
 
+/**
+ * A memory scope that provides access to the properties of the active dialog.
+ * This scope binds to the active dialog and clones its properties for use in memory.
+ */
 export class ClassMemoryScope extends MemoryScope {
   /**
-     * Initializes a new instance of the ClassMemoryScope class.
-     *
-     * @param name Name of the scope class.
-     */
+   * Initializes a new instance of the ClassMemoryScope class.
+   *
+   * @param name - Name of the scope class. Defaults to `ScopePath.class`.
+   */
   constructor (name = ScopePath.class) {
     super(name, false)
   }
 
   /**
-     * Gets the backing memory for this scope.
-     *
-     * @param dialogContext The DialogContext object for this turn.
-     * @returns The memory for the scope.
-     */
+   * Gets the backing memory for this scope.
+   *
+   * @param dialogContext - The DialogContext object for this turn.
+   * @returns The memory for the scope, containing cloned properties of the active dialog.
+   */
   getMemory (dialogContext: DialogContext): object {
     // if active dialog is a container dialog then "dialog" binds to it
     if (dialogContext.activeDialog) {
@@ -52,11 +56,11 @@ export class ClassMemoryScope extends MemoryScope {
   }
 
   /**
-     * Override to find the dialog instance referenced by the scope.
-     *
-     * @param dialogContext Current dialog context.
-     * @returns The dialog instance referenced by the scope.
-     */
+   * Override to find the dialog instance referenced by the scope.
+   *
+   * @param dialogContext - Current dialog context.
+   * @returns The dialog instance referenced by the scope, or undefined if not found.
+   */
   protected onFindDialog (dialogContext: DialogContext): Dialog | undefined {
     return dialogContext.findDialog(dialogContext.activeDialog.id)
   }

package/src/memory/scopes/dialogClassMemoryScope.ts

@@ -8,19 +8,25 @@ import { DialogContext } from '../../dialogContext'
 import { Dialog } from '../../dialog'
 import { DialogContainer } from '../../dialogContainer'
 
+/**
+ * A memory scope that provides access to the properties of the active dialog class.
+ * This scope resolves to the active dialog if it is a container, or to its parent dialog.
+ */
 export class DialogClassMemoryScope extends ClassMemoryScope {
   /**
-     * Initializes a new instance of the DialogClassMemoryScope class.
-     */
+   * Initializes a new instance of the DialogClassMemoryScope class.
+   */
   constructor () {
     super(ScopePath.dialogClass)
   }
 
   /**
-     * @protected
-     * @param dialogContext The DialogContext object for this turn.
-     * @returns The current Dialog.
-     */
+   * @protected
+   * Finds the dialog instance referenced by the scope.
+   *
+   * @param dialogContext - The DialogContext object for this turn.
+   * @returns The current dialog, or its parent dialog if applicable.
+   */
   protected onFindDialog (dialogContext: DialogContext): Dialog | undefined {
     // Is the active dialog a container?
     const dialog = dialogContext.findDialog(dialogContext.activeDialog.id)

package/src/memory/scopes/dialogContextMemoryScope.ts

@@ -7,20 +7,24 @@ import { DialogContext } from '../../dialogContext'
 import { MemoryScope } from './memoryScope'
 import { ScopePath } from '../scopePath'
 
+/**
+ * A memory scope that provides access to the dialog context.
+ * This scope includes information about the active dialog, its parent, and the dialog stack.
+ */
 export class DialogContextMemoryScope extends MemoryScope {
   /**
-     * Initializes a new instance of the `DialogContextMemoryScope` class.
-     */
+   * Initializes a new instance of the `DialogContextMemoryScope` class.
+   */
   constructor () {
     super(ScopePath.dialogContext, false)
   }
 
   /**
-     * Gets the backing memory for this scope.
-     *
-     * @param dialogContext The `DialogContext` object for this turn.
-     * @returns Memory for the scope.
-     */
+   * Gets the backing memory for this scope.
+   *
+   * @param dialogContext - The `DialogContext` object for this turn.
+   * @returns An object containing the dialog stack, active dialog ID, and parent dialog ID.
+   */
   getMemory (dialogContext: DialogContext): Record<'stack' | 'activeDialog' | 'parent', unknown> {
     const stack = []
     let currentDialogContext: DialogContext | undefined = dialogContext

package/src/memory/scopes/dialogMemoryScope.ts

@@ -7,20 +7,24 @@ import { ScopePath } from '../scopePath'
 import { DialogContext } from '../../dialogContext'
 import { DialogContainer } from '../../dialogContainer'
 
+/**
+ * A memory scope that provides access to the active dialog's state.
+ * This scope binds to the active dialog if it is a container, or to its parent dialog if applicable.
+ */
 export class DialogMemoryScope extends MemoryScope {
   /**
-     * Initializes a new instance of the DialogMemoryScope class.
-     */
+   * Initializes a new instance of the DialogMemoryScope class.
+   */
   constructor () {
     super(ScopePath.dialog)
   }
 
   /**
-     * Gets the backing memory for this scope.
-     *
-     * @param dialogContext The DialogContext object for this turn.
-     * @returns The memory for the scope.
-     */
+   * Gets the backing memory for this scope.
+   *
+   * @param dialogContext - The DialogContext object for this turn.
+   * @returns The memory for the scope.
+   */
   getMemory (dialogContext: DialogContext): object {
     // If active dialog is a container dialog then "dialog" binds to it.
     // Otherwise the "dialog" will bind to the dialogs parent assuming it
@@ -35,11 +39,12 @@ export class DialogMemoryScope extends MemoryScope {
   }
 
   /**
-     * Changes the backing object for the memory scope.
-     *
-     * @param dialogContext The DialogContext object for this turn.
-     * @param memory Memory object to set for the scope.
-     */
+   * Changes the backing object for the memory scope.
+   *
+   * @param dialogContext - The DialogContext object for this turn.
+   * @param memory - Memory object to set for the scope.
+   * @throws Will throw an error if the memory object is undefined or if no active dialog is found.
+   */
   setMemory (dialogContext: DialogContext, memory: object): void {
     if (memory === undefined) {
       throw new Error('DialogMemoryScope.setMemory: undefined memory object passed in.')
@@ -62,10 +67,12 @@ export class DialogMemoryScope extends MemoryScope {
   }
 
   /**
-     * @private
-     * @param dialogContext The DialogContext object for this turn.
-     * @returns A boolean indicating whether is a cointainer or not.
-     */
+   * Determines if the given dialog context is a container.
+   *
+   * @private
+   * @param dialogContext - The DialogContext object for this turn.
+   * @returns A boolean indicating whether the dialog context is a container.
+   */
   private isContainer (dialogContext: DialogContext): boolean {
     if (dialogContext !== undefined && dialogContext.activeDialog !== undefined) {
       const dialog = dialogContext.findDialog(dialogContext.activeDialog.id)

package/src/memory/scopes/turnMemoryScope.ts

@@ -12,22 +12,23 @@ import { DialogContext } from '../../dialogContext'
 const TURN_STATE = 'turn'
 
 /**
- * TurnMemoryScope represents memory scoped to the current turn.
+ * A memory scope that provides access to the turn's state.
+ * This scope is used to store and retrieve information specific to the current turn.
  */
 export class TurnMemoryScope extends MemoryScope {
   /**
-     * Initializes a new instance of the TurnMemoryScope class.
-     */
+   * Initializes a new instance of the TurnMemoryScope class.
+   */
   constructor () {
     super(ScopePath.turn, true)
   }
 
   /**
-     * Get the backing memory for this scope.
-     *
-     * @param dialogContext The DialogContext for this turn.
-     * @returns The memory for the scope.
-     */
+   * Gets the backing memory for this scope.
+   *
+   * @param dialogContext - The DialogContext object for this turn.
+   * @returns The memory for the scope.
+   */
   getMemory (dialogContext: DialogContext): object {
     let memory = dialogContext.context.turnState.get(TURN_STATE)
     if (typeof memory !== 'object') {
@@ -39,11 +40,11 @@ export class TurnMemoryScope extends MemoryScope {
   }
 
   /**
-     * Changes the backing object for the memory scope.
-     *
-     * @param dialogContext The DialogContext for this turn.
-     * @param memory Memory object to set for the scope.
-     */
+   * Changes the backing object for the memory scope.
+   *
+   * @param dialogContext - The DialogContext object for this turn.
+   * @param memory - Memory object to set for the scope.
+   */
   setMemory (dialogContext: DialogContext, memory: object): void {
     if (memory === undefined) {
       throw new Error('TurnMemoryScope.setMemory: undefined memory object passed in.')

package/src/memory/turnPath.ts

@@ -4,42 +4,78 @@
  */
 
 /**
- * Defines path for avaiable turns.
+ * Defines path for available turns.
  */
 export class TurnPath {
-  /// The result from the last dialog that was called.
-  static readonly lastResult = 'turn.lastresult'
+  /**
+   * The result from the last dialog that was called.
+   * @constant A string key representing the last result path (`'turn.lastresult'`).
+   */
+  static readonly lastResult: string = 'turn.lastresult'
 
-  /// The current activity for the turn.
-  static readonly activity = 'turn.activity'
+  /**
+   * The current activity for the turn.
+   * @constant A string key representing the activity path (`'turn.activity'`).
+   */
+  static readonly activity: string = 'turn.activity'
 
-  /// The recognized result for the current turn.
-  static readonly recognized = 'turn.recognized'
+  /**
+   * The recognized result for the current turn.
+   * @constant A string key representing the recognized result path (`'turn.recognized'`).
+   */
+  static readonly recognized: string = 'turn.recognized'
 
-  /// Path to the top intent.
-  static readonly topIntent = 'turn.recognized.intent'
+  /**
+   * Path to the top intent.
+   * @constant A string key representing the top intent path (`'turn.recognized.intent'`).
+   */
+  static readonly topIntent: string = 'turn.recognized.intent'
 
-  /// Path to the top score.
-  static readonly topScore = 'turn.recognized.score'
+  /**
+   * Path to the top score.
+   * @constant A string key representing the top score path (`'turn.recognized.score'`).
+   */
+  static readonly topScore: string = 'turn.recognized.score'
 
-  /// Original text.
-  static readonly text = 'turn.recognized.text'
+  /**
+   * Original text.
+   * @constant A string key representing the original text path (`'turn.recognized.text'`).
+   */
+  static readonly text: string = 'turn.recognized.text'
 
-  /// Original utterance split into unrecognized strings.
-  static readonly unrecognizedText = 'turn.unrecognizedText'
+  /**
+   * Original utterance split into unrecognized strings.
+   * @constant A string key representing the unrecognized text path (`'turn.unrecognizedText'`).
+   */
+  static readonly unrecognizedText: string = 'turn.unrecognizedText'
 
-  /// Entities that were recognized from text.
-  static readonly recognizedEntities = 'turn.recognizedEntities'
+  /**
+   * Entities that were recognized from text.
+   * @constant A string key representing the recognized entities path (`'turn.recognizedEntities'`).
+   */
+  static readonly recognizedEntities: string = 'turn.recognizedEntities'
 
-  /// If true an interruption has occured.
-  static readonly interrupted = 'turn.interrupted'
+  /**
+   * If true, an interruption has occurred.
+   * @constant A string key representing the interrupted path (`'turn.interrupted'`).
+   */
+  static readonly interrupted: string = 'turn.interrupted'
 
-  /// The current dialog event (set during event processings).
-  static readonly dialogEvent = 'turn.dialogEvent'
+  /**
+   * The current dialog event (set during event processing).
+   * @constant A string key representing the dialog event path (`'turn.dialogEvent'`).
+   */
+  static readonly dialogEvent: string = 'turn.dialogEvent'
 
-  /// Used to track that we don't end up in infinite loop of RepeatDialogs().
-  static readonly repeatedIds = 'turn.repeatedIds'
+  /**
+   * Used to track that we don't end up in an infinite loop of RepeatDialogs().
+   * @constant A string key representing the repeated IDs path (`'turn.repeatedIds'`).
+   */
+  static readonly repeatedIds: string = 'turn.repeatedIds'
 
-  /// This is a bool which if set means that the turncontext.activity has been consumed by some component in the system.
-  static readonly activityProcessed = 'turn.activityProcessed'
+  /**
+   * Indicates whether the turncontext.activity has been consumed by some component in the system.
+   * @constant A string key representing the activity processed path (`'turn.activityProcessed'`).
+   */
+  static readonly activityProcessed: string = 'turn.activityProcessed'
 }

package/src/prompts/attachmentPrompt.ts

@@ -10,7 +10,7 @@ import { Attachment, InputHints } from '@microsoft/agents-activity'
  * Prompts a user to upload attachments like images.
  *
  * @remarks
- * By default the prompt will return to the calling dialog an `Attachment[]`.
+ * By default the prompt will return to the calling dialog an {@link Attachment[]}.
  */
 export class AttachmentPrompt extends Prompt<Attachment[]> {
   // eslint-disable-next-line @typescript-eslint/no-useless-constructor