@microsoft/agents-hosting-dialogs 0.1.49

package/src/prompts/textPrompt.ts

@@ -0,0 +1,82 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { InputHints, TurnContext } from '@microsoft/agents-hosting'
+import { Prompt, PromptOptions, PromptRecognizerResult, PromptValidator } from './prompt'
+import { DialogContext } from '../dialogContext'
+import { DialogEvent } from '../dialogEvent'
+
+/**
+ * Prompts a user to enter some text.
+ *
+ * @remarks
+ * By default the prompt will return to the calling dialog a `string` representing the users reply.
+ */
+export class TextPrompt extends Prompt<string> {
+  // eslint-disable-next-line @typescript-eslint/no-useless-constructor
+  constructor (dialogId?: string, validator?: PromptValidator<string>) {
+    super(dialogId, validator)
+  }
+
+  /**
+     * Prompts the user for input.
+     *
+     * @param context TurnContext, context for the current
+     * turn of conversation with the user.
+     * @param state Contains state for the current instance of the prompt on the dialog stack.
+     * @param options A PromptOptions object constructed
+     * from the options initially provided in the call to Prompt.
+     * @param isRetry `true` if this is the first time this prompt dialog instance
+     * on the stack is prompting the user for input; otherwise, false.
+     * @returns A `Promise` representing the asynchronous operation.
+     */
+  protected async onPrompt (
+    context: TurnContext,
+    state: any,
+    options: PromptOptions,
+    isRetry: boolean
+  ): Promise<void> {
+    if (isRetry && options.retryPrompt) {
+      await context.sendActivity(options.retryPrompt, undefined, InputHints.ExpectingInput)
+    } else if (options.prompt) {
+      await context.sendActivity(options.prompt, undefined, InputHints.ExpectingInput)
+    }
+  }
+
+  /**
+     * Attempts to recognize the user's input.
+     *
+     * @param context TurnContext, context for the current
+     * turn of conversation with the user.
+     * @param _state Contains state for the current instance of the prompt on the dialog stack.
+     * @param _options A PromptOptions object constructed
+     * from the options initially provided in the call to Prompt.
+     * @returns A `Promise` representing the asynchronous operation.
+     */
+  protected async onRecognize (
+    context: TurnContext,
+    _state: any,
+    _options: PromptOptions
+  ): Promise<PromptRecognizerResult<string>> {
+    const value: string = context.activity.text
+
+    return typeof value === 'string' && value.length > 0 ? { succeeded: true, value } : { succeeded: false }
+  }
+
+  /**
+     * Called before an event is bubbled to its parent.
+     *
+     * @param _dc The DialogContext for the current
+     * turn of conversation.
+     * @param _event DialogEvent, the event being raised.
+     * @returns Whether the event is handled by the current dialog and further processing should stop.
+     * @remarks
+     * This is a good place to perform interception of an event as returning `true` will prevent
+     * any further bubbling of the event to the dialogs parents and will also prevent any child
+     * dialogs from performing their default processing.
+     */
+  protected async onPreBubbleEvent (_dc: DialogContext, _event: DialogEvent): Promise<boolean> {
+    return false
+  }
+}

package/src/recognizer.ts

@@ -0,0 +1,127 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { Activity } from '@microsoft/agents-hosting'
+import { Configurable } from './configurable'
+import { DialogContext } from './dialogContext'
+import omit from 'lodash/omit'
+import { RecognizerResult, getTopScoringIntent } from './recognizerResult'
+
+export interface RecognizerConfiguration {
+  id?: string;
+}
+
+/**
+ * Recognizer base class.
+ */
+export class Recognizer extends Configurable implements RecognizerConfiguration {
+  id?: string
+  /**
+     * To recognize intents and entities in a users utterance.
+     *
+     * @param {DialogContext} _dialogContext Dialog Context.
+     * @param {Partial<Activity>} _activity Activity.
+     * @param {Record<string, string>} _telemetryProperties Additional properties to be logged to telemetry with event.
+     * @param {Record<string, number>} _telemetryMetrics Additional metrics to be logged to telemetry with event.
+     */
+  recognize (
+    _dialogContext: DialogContext,
+    _activity: Partial<Activity>,
+    _telemetryProperties?: Record<string, string>,
+    _telemetryMetrics?: Record<string, number>
+  ): Promise<RecognizerResult> {
+    throw new Error('Please implement recognize function.')
+  }
+
+  /**
+     * Creates choose intent result in the case that there are conflicting or ambiguous signals from the recognizers.
+     *
+     * @param {Record<string, RecognizerResult>} recognizerResults A group of recognizer results.
+     * @returns {RecognizerResult} Recognizer result which is ChooseIntent.
+     */
+  protected createChooseIntentResult (recognizerResults: Record<string, RecognizerResult>): RecognizerResult {
+    let text: string = ''
+    let sentiment: Record<string, any> = {}
+        type candidateType = { id: string; intent: string; score: number; result: RecognizerResult }
+        const candidates = Object.entries(recognizerResults).reduce((candidates: candidateType[], [key, result]) => {
+          text = result.text
+          sentiment = result.sentiment
+          const { intent, score } = getTopScoringIntent(result)
+          if (intent !== 'None') {
+            candidates.push({
+              id: key,
+              intent,
+              score,
+              result,
+            })
+          }
+          return candidates
+        }, [])
+
+        if (candidates.length) {
+          const recognizerResult: RecognizerResult = {
+            text,
+            intents: { ChooseIntent: { score: 1.0 } },
+            candidates,
+            entities: {},
+          }
+          return recognizerResult
+        }
+
+        // just return a `None` intent.
+        const recognizerResult: RecognizerResult = {
+          text,
+          intents: { None: { score: 1.0 } },
+          entities: {},
+          sentiment,
+        }
+        return recognizerResult
+  }
+
+  /**
+     * Uses the RecognizerResult to create a list of properties to be included when tracking the result in telemetry.
+     *
+     * @param {RecognizerResult} recognizerResult Recognizer Result.
+     * @param {Record<string, string>} telemetryProperties A list of properties to append or override the properties created using the RecognizerResult.
+     * @param {DialogContext} _dialogContext Dialog Context.
+     * @returns {Record<string, string>} A collection of properties that can be included when calling the TrackEvent method on the TelemetryClient.
+     */
+  protected fillRecognizerResultTelemetryProperties (
+    recognizerResult: RecognizerResult,
+    telemetryProperties: Record<string, string>,
+    _dialogContext?: DialogContext
+  ): Record<string, string> {
+    const { intent, score } = getTopScoringIntent(recognizerResult)
+    const intents = Object.entries(recognizerResult.intents)
+
+    const properties: Record<string, string > = {
+      Text: recognizerResult.text,
+      AlteredText: recognizerResult.alteredText ?? '',
+      TopIntent: intents.length > 0 ? intent : '',
+      TopIntentScore: intents.length > 0 ? score.toString() : '',
+      Intents: intents.length > 0 ? JSON.stringify(recognizerResult.intents) : '',
+      Entities: recognizerResult.entities ? JSON.stringify(recognizerResult.entities) : '',
+      AdditionalProperties: JSON.stringify(
+        omit(recognizerResult, ['text', 'alteredText', 'intents', 'entities'])
+      ),
+    }
+
+    if (telemetryProperties) {
+      return Object.assign({}, properties, telemetryProperties)
+    }
+
+    return properties
+  }
+
+  protected stringifyAdditionalPropertiesOfRecognizerResult (recognizerResult: RecognizerResult): string {
+    const generalProperties = new Set(['text', 'alteredText', 'intents', 'entities'])
+    const additionalProperties: { [key: string]: string } = {}
+    for (const key in recognizerResult) {
+      if (!generalProperties.has(key)) {
+        additionalProperties[key] = recognizerResult[key]
+      }
+    }
+    return Object.keys(additionalProperties).length > 0 ? JSON.stringify(additionalProperties) : ''
+  }
+}

package/src/recognizerResult.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { IntentScore } from './intentScore'
+
+/**
+ * Value returned from a recognizer.
+ */
+export interface RecognizerResult {
+  text: string;
+  alteredText?: string;
+  intents: Record<string, IntentScore>;
+  entities?: any;
+  [propName: string]: any;
+}
+
+export const getTopScoringIntent = (result: RecognizerResult): { intent: string; score: number } => {
+  if (!result || !result.intents) {
+    throw new Error('result is empty')
+  }
+
+  let topIntent = ''
+  let topScore = -1
+  for (const [intentName, intent] of Object.entries(result.intents)) {
+    const score = intent.score ?? -1
+    if (!topIntent || score > topScore) {
+      topIntent = intentName
+      topScore = score
+    }
+  }
+
+  return {
+    intent: topIntent,
+    score: topScore,
+  }
+}

package/src/serviceCollection.ts

@@ -0,0 +1,305 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import assert, { ok } from 'assert'
+import { DepGraph } from 'dependency-graph'
+
+/**
+ * Factory describes a generic factory function signature. The type is generic over a few parameters:
+ *
+ * @template Type type the factory produces
+ * @template Initial true if the `initialValue` passed to the factory must be defined
+ */
+export type Factory<Type, Initial extends boolean> = (
+  initialValue: Initial extends true ? Type : Type | undefined,
+) => Type
+
+/**
+ * DependencyFactory is a function signature that produces an instance that depends on a set of
+ * other services. The type is generic over a few parameters:
+ *
+ * @template Type type the factory produces
+ * @template Dependencies the services this factory function depends on
+ * @template Initial true if the `initialValue` passed to the factory must be defined
+ */
+export type DependencyFactory<Type, Dependencies, Initial extends boolean> = (
+  dependencies: Dependencies,
+  initialValue: Initial extends true ? Type : Type | undefined,
+) => Type
+
+/**
+ * ServiceCollection is an interface that describes a set of methods to register services. This, in a lighter way,
+ * mimics the .NET dependency injection service collection functionality, except for instances rather than types.
+ */
+export class ServiceCollection {
+  // We store the full set of dependencies as a workaround to the fact that `DepGraph` throws an error if you
+  // attempt to register a dependency to a node that does not yet exist.
+  private readonly dependencies: Map<string, string[]> = new Map<string, string[]>()
+
+  /**
+     * `DepGraph` is a dependency graph data structure. In our case, the services we support are encoded as a
+     * dependency graph where nodes are named with a key and store a list of factory methods.
+     */
+  private readonly graph = new DepGraph<Array<DependencyFactory<unknown, Record<string, unknown>, true>>>()
+
+  /**
+     * Cache constructed instances for reuse
+     */
+  private cache: Record<string, unknown> = {}
+
+  /**
+     * Construct a Providers instance
+     *
+     * @template S services interface
+     * @param defaultServices default set of services
+     */
+  constructor (defaultServices: Record<string, unknown> = {}) {
+    Object.entries(defaultServices).forEach(([key, instance]) => {
+      this.addInstance(key, instance)
+    })
+  }
+
+  /**
+     * Register an instance by key. This will overwrite existing instances.
+     *
+     * @param key key of the instance being provided
+     * @param instance instance to provide
+     * @returns this for chaining
+     */
+  addInstance<InstanceType>(key: string, instance: InstanceType): this {
+    if (this.graph.hasNode(key)) {
+      this.graph.removeNode(key)
+    }
+
+    this.graph.addNode(key, [() => instance])
+    return this
+  }
+
+  /**
+     * Register a factory for a key.
+     *
+     * @param key key that factory will provide
+     * @param factory function that creates an instance to provide
+     * @returns this for chaining
+     */
+  addFactory<InstanceType>(key: string, factory: Factory<InstanceType, false>): this
+
+  /**
+     * Register a factory for a key with a set of dependencies.
+     *
+     * @param key key that factory will provide
+     * @param dependencies set of things this instance depends on. Will be provided to factory function via `services`.
+     * @param factory function that creates an instance to provide
+     * @returns this for chaining
+     */
+  addFactory<InstanceType, Dependencies>(
+    key: string,
+    dependencies: string[],
+    factory: DependencyFactory<InstanceType, Dependencies, false>,
+  ): this
+
+  /**
+     * @internal
+     */
+  addFactory<InstanceType, Dependencies>(
+    key: string,
+    depsOrFactory: string[] | Factory<InstanceType, false>,
+    maybeFactory?: DependencyFactory<InstanceType, Dependencies, false>
+  ): this {
+    const dependencies = Array.isArray(depsOrFactory) ? depsOrFactory : undefined
+
+    let factory: DependencyFactory<InstanceType, Dependencies, false> | undefined = maybeFactory
+    if (!factory && typeof depsOrFactory === 'function') {
+      factory = (_services, value) => depsOrFactory(value)
+    }
+
+    // Asserts factory is not undefined
+    ok(factory, 'illegal invocation with undefined factory')
+
+    if (dependencies) {
+      this.dependencies.set(key, dependencies)
+    }
+
+    // If the graph already has this key, fetch its data and remove it (to be replaced)
+    let factories: unknown[] = []
+    if (this.graph.hasNode(key)) {
+      factories = this.graph.getNodeData(key)
+      this.graph.removeNode(key)
+    }
+
+    this.graph.addNode(key, factories.concat(factory) as any)
+
+    return this
+  }
+
+  /**
+     * Register a factory (that expects the initial value that is not undefined) for a key.
+     *
+     * @param key key of the instance being provided
+     * @param instance instance to provide
+     * @returns this for chaining
+     */
+  composeFactory<InstanceType>(key: string, factory: Factory<InstanceType, true>): this
+
+  /**
+     * Register a factory (that expects an initial value that is not undefined) for a key
+     * with a set of dependencies.
+     *
+     * @param key key that factory will provide
+     * @param dependencies set of things this instance depends on. Will be provided to factory function via `services`.
+     * @param factory function that creates an instance to provide
+     * @returns this for chaining
+     */
+  composeFactory<InstanceType, Dependencies>(
+    key: string,
+    dependencies: string[],
+    factory: DependencyFactory<InstanceType, Dependencies, true>,
+  ): this
+
+  /**
+     * @internal
+     */
+  composeFactory<InstanceType, Dependencies>(
+    key: string,
+    depsOrFactory: string[] | Factory<InstanceType, true>,
+    maybeFactory?: DependencyFactory<InstanceType, Dependencies, true>
+  ): this {
+    if (maybeFactory) {
+      return this.addFactory<InstanceType, Dependencies>(
+        key,
+        Array.isArray(depsOrFactory) ? depsOrFactory : [],
+        (dependencies, value) => {
+          ok(value, `unable to create ${key}, initial value undefined`)
+
+          return maybeFactory(dependencies, value)
+        }
+      )
+    } else {
+      ok(typeof depsOrFactory === 'function', 'illegal invocation with undefined factory')
+
+      return this.addFactory<InstanceType>(key, (value) => {
+        ok(value, `unable to create ${key}, initial value undefined`)
+
+        return depsOrFactory(value)
+      })
+    }
+  }
+
+  // Register dependencies and then build nodes. Note: `nodes` is a function because ordering may
+  // depend on results of dependency registration
+  private buildNodes<ReturnType = Record<string, unknown>>(
+    generateNodes: () => string[],
+    reuseServices: Record<string, unknown> = {}
+  ): ReturnType {
+    // Consume all dependencies and then reset so updating registrations without re-registering
+    // dependencies works
+    this.dependencies.forEach((dependencies, node) =>
+      dependencies.forEach((dependency) => this.graph.addDependency(node, dependency))
+    )
+
+    // Generate nodes after registering dependencies so ordering is correct
+    const nodes = generateNodes()
+
+    const services = nodes.reduce(
+      (services, service) => {
+        // Extra precaution
+        if (!this.graph.hasNode(service)) {
+          return services
+        }
+
+        // Helper to generate return value
+        const assignValue = (value: unknown) => ({
+          ...services,
+          [service]: value,
+        })
+
+        // Optionally reuse existing service
+        const reusedService = reuseServices[service]
+        if (reusedService !== undefined) {
+          return assignValue(reusedService)
+        }
+
+        // Each node stores a list of factory methods.
+        const factories = this.graph.getNodeData(service)
+
+        // Produce the instance by reducing those factories, passing the instance along for composition.
+        const instance = factories.reduce(
+          (value, factory) => factory(services, value),
+                    <unknown>services[service]
+        )
+
+        return assignValue(instance)
+      },
+            <Record<string, unknown>>{}
+    )
+
+    // Cache results for subsequent invocations that may desire pre-constructed instances
+    Object.assign(this.cache, services)
+
+    return services as ReturnType
+  }
+
+  /**
+     * Build a single service.
+     *
+     * @param key service to build
+     * @param deep reconstruct all dependencies
+     * @returns the service instance, or undefined
+     */
+  makeInstance<InstanceType = unknown>(key: string, deep = false): InstanceType | undefined {
+    // If this is not a deep reconstruction, reuse any services that `key` depends on
+    let initialServices: Record<string, unknown> | undefined
+    if (!deep) {
+      const { [key]: _, ...cached } = this.cache
+      initialServices = cached
+    }
+
+    const services = this.buildNodes<Record<string, InstanceType | undefined>>(
+      () => this.graph.dependenciesOf(key).concat(key),
+      initialServices
+    )
+
+    return services[key]
+  }
+
+  /**
+     * Build a single service and assert that it is not undefined.
+     *
+     * @param key service to build
+     * @param deep reconstruct all dependencies
+     * @returns the service instance
+     */
+  mustMakeInstance<InstanceType = unknown>(key: string, deep = false): InstanceType {
+    const instance = this.makeInstance<InstanceType>(key, deep)
+    assert.ok(instance, `\`${key}\` instance undefined!`)
+
+    return instance
+  }
+
+  /**
+     * Build the full set of services.
+     *
+     * @returns all resolved services
+     */
+  makeInstances<InstancesType>(): InstancesType {
+    return this.buildNodes<InstancesType>(() => this.graph.overallOrder())
+  }
+
+  /**
+     * Build the full set of services, asserting that the specified keys are not undefined.
+     *
+     * @param keys instances that must be not undefined
+     * @returns all resolve services
+     */
+  mustMakeInstances<InstancesType extends Record<string, unknown> = Record<string, unknown>>(
+    ...keys: string[]
+  ): InstancesType {
+    const instances = this.makeInstances<InstancesType>()
+
+    keys.forEach((key) => {
+      assert.ok(instances[key], `\`${key}\` instance undefined!`)
+    })
+
+    return instances
+  }
+}

package/src/stringUtils.ts

@@ -0,0 +1,62 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Helper class containing string utility methods.
+ */
+export class StringUtils {
+  /**
+     * Truncate string with ...
+     *
+     * @param text Text.
+     * @param length Length to truncate text.
+     * @returns Original string modified.
+     */
+  static ellipsis (text: string, length: number): string {
+    text = text || ''
+    if (text.length <= length) {
+      return text
+    }
+
+    return `${text.substr(0, length)}...`
+  }
+
+  /**
+     * UniqueHash - create a unique hash from a string.
+     *
+     * @remarks
+     * The source for this function was derived from the following article:
+     *
+     * https://werxltd.com/wp/2010/05/13/javascript-implementation-of-javas-string-hashcode-method/
+     * @param text Text to hash.
+     * @returns A string which is an unique hash.
+     */
+  static hash (text: string): string {
+    const length = text.length
+    let hash = 0
+    for (let i = 0; i < length; i++) {
+      const chr = text.charCodeAt(i)
+      hash = (hash << 5) - hash + chr
+      hash |= 0 // Convert to 32 bit integer
+    }
+    return hash.toString()
+  }
+
+  /**
+     * EllipsisHash - create truncated string with unique hash for the truncated part.
+     *
+     * @param text Text to truncate.
+     * @param length Length to truncate at.
+     * @returns The truncated string with unique hash for the truncated part.
+     */
+  static ellipsisHash (text: string, length: number): string {
+    text = text || ''
+    if (text.length <= length) {
+      return text
+    }
+
+    return `${this.ellipsis(text, length)}${this.hash(text)}`
+  }
+}

package/src/template.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { DialogContext } from './dialogContext'
+
+/**
+ * Defines Template interface for binding data to T.
+ */
+export interface TemplateInterface<T, D = Record<string, unknown>> {
+  /**
+     * Given the turn context bind to the data to create the object
+     *
+     * @param dialogContext DialogContext.
+     * @param data Data to bind to.
+     * @returns Instance of T.
+     */
+  bind(dialogContext: DialogContext, data?: D): Promise<T>;
+}