From e9ac895d8ae6e8beaba51214d36c15061db2da20 Mon Sep 17 00:00:00 2001 From: Hisham A Date: Wed, 16 Aug 2017 12:21:09 -0600 Subject: [PATCH] [annyang] add typings (#19031) --- types/annyang/annyang-tests.ts | 71 ++++++++++ types/annyang/index.d.ts | 230 +++++++++++++++++++++++++++++++++ types/annyang/tsconfig.json | 22 ++++ types/annyang/tslint.json | 1 + 4 files changed, 324 insertions(+) create mode 100644 types/annyang/annyang-tests.ts create mode 100644 types/annyang/index.d.ts create mode 100644 types/annyang/tsconfig.json create mode 100644 types/annyang/tslint.json diff --git a/types/annyang/annyang-tests.ts b/types/annyang/annyang-tests.ts new file mode 100644 index 0000000000..56dd51f417 --- /dev/null +++ b/types/annyang/annyang-tests.ts @@ -0,0 +1,71 @@ +import { Annyang, CommandOption } from 'annyang'; + +declare let annyang: Annyang; +declare let console: any; + +// Tests based on API documentation at https://github.com/TalAter/annyang/blob/master/docs/README.md + +function testStartListening() { + annyang.start({ autoRestart: false }); // $ExpectType void + annyang.start({ autoRestart: false, continuous: false }); // $ExpectType void +} + +function testAddComments() { + let helloFunction = (): string => { + return 'hello'; + }; + + let commands: CommandOption = {'hello :name': helloFunction, howdy: helloFunction}; + let commands2: CommandOption = {hi: helloFunction}; + + annyang.addCommands(commands); // $ExpectType void + annyang.addCommands(commands2); // $ExpectType void + annyang.removeCommands(); // $ExpectType void + annyang.addCommands(commands); // $ExpectType void + annyang.removeCommands('hello'); // $ExpectType void + annyang.removeCommands(['howdy', 'hi']); // $ExpectType void +} + +let notConnected = () => { console.error('network connection error'); }; + +function testAddCallback() { + annyang.addCallback('error', () => console.error('There was an error!') ); // $ExpectType void + + // $ExpectType void + annyang.addCallback('resultMatch', (userSaid, commandText, phrases) => { + console.log(userSaid); + console.log(commandText); + console.log(phrases); + }); + + annyang.addCallback('errorNetwork', notConnected, annyang); // $ExpectType void +} + +function testRemoveCallback() { + let start = () => { console.log('start'); }; + let end = () => { console.log('end'); }; + + annyang.addCallback('start', start); // $ExpectType void + annyang.addCallback('end', end); // $ExpectType void + + annyang.removeCallback(); // $ExpectType void + + annyang.removeCallback('end'); // $ExpectType void + + annyang.removeCallback('start', start); // $ExpectType void + + annyang.removeCallback(undefined, start); // $ExpectType void +} + +function testTrigger() { + annyang.trigger('Time for some thrilling heroics'); + + // $ExpectType void + annyang.trigger( + ['Time for some thrilling heroics', 'Time for some thrilling aerobics'] + ); +} + +function testIsListening() { + annyang.isListening(); // $ExpectType boolean +} diff --git a/types/annyang/index.d.ts b/types/annyang/index.d.ts new file mode 100644 index 0000000000..fee0cb9acb --- /dev/null +++ b/types/annyang/index.d.ts @@ -0,0 +1,230 @@ +// Type definitions for annyang 2.6 +// Project: https://www.talater.com/annyang/ +// Definitions by: Hisham Al-Shurafa +// Lukas Klinzing +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped + +/** + * Options for function `start` + * + * @export + * @interface StartOptions + */ +export interface StartOptions { + /** + * Should annyang restart itself if it is closed indirectly, because of silence or window conflicts? + * + * @type {boolean} + */ + autoRestart?: boolean; + /** + * Allow forcing continuous mode on or off. Annyang is pretty smart about this, so only set this if you know what you're doing. + * + * @type {boolean} + */ + continuous?: boolean; +} + +/** + * A command option that supports custom regular expressions + * + * @export + * @interface CommandOptionRegex + */ +export interface CommandOptionRegex { + /** + * @type {RegExp} + */ + regexp: RegExp; + /** + * @type {() => any} + */ + callback(): void; +} + +/** + * Commands that annyang should listen to + * + * #### Examples: + * ````javascript + * {'hello :name': helloFunction, 'howdy': helloFunction}; + * {'hi': helloFunction}; + * ```` + * @export + * @interface CommandOption + */ +export interface CommandOption { + [command: string]: CommandOptionRegex | (() => void); +} + +/** + * Supported Events that will be triggered to listeners, you attach using `annyang.addCallback()` + * + * `start` - Fired as soon as the browser's Speech Recognition engine starts listening + * `error` - Fired when the browser's Speech Recogntion engine returns an error, this generic error callback will be followed by more accurate error callbacks (both will fire if both are defined) + * `errorNetwork` - Fired when Speech Recognition fails because of a network error + * `errorPermissionBlocked` - Fired when the browser blocks the permission request to use Speech Recognition. + * `errorPermissionDenied` - Fired when the user blocks the permission request to use Speech Recognition. + * `end` - Fired when the browser's Speech Recognition engine stops + * `result` - Fired as soon as some speech was identified. This generic callback will be followed by either the `resultMatch` or `resultNoMatch` callbacks. + * Callback functions registered to this event will include an array of possible phrases the user said as the first argument + * `resultMatch` - Fired when annyang was able to match between what the user said and a registered command + * Callback functions registered to this event will include three arguments in the following order: + * * The phrase the user said that matched a command + * * The command that was matched + * * An array of possible alternative phrases the user might've said + * `resultNoMatch` - Fired when what the user said didn't match any of the registered commands. + * Callback functions registered to this event will include an array of possible phrases the user might've said as the first argument + */ +export type Events = + 'start' | + 'soundstart' | + 'error' | + 'end' | + 'result' | + 'resultMatch' | + 'resultNoMatch' | + 'errorNetwork' | + 'errorPermissionBlocked' | + 'errorPermissionDenied'; + +export interface Annyang { + /** + * Start listening. + * It's a good idea to call this after adding some commands first, but not mandatory. + * + * @param {StartOptions} options + */ + start(options?: StartOptions): void; + + /** + * Stop listening, and turn off mic. + * + */ + abort(): void; + + /** + * Pause listening. annyang will stop responding to commands (until the resume or start methods are called), without turning off the browser's SpeechRecognition engine or the mic. + * + */ + pause(): void; + + /** + * Resumes listening and restores command callback execution when a result matches. + * If SpeechRecognition was aborted (stopped), start it. + * + */ + resume(): void; + + /** + * Turn on output of debug messages to the console. Ugly, but super-handy! + * + * @export + * @param {boolean} [newState=true] Turn on/off debug messages + */ + debug(newState?: boolean): void; + + /** + * Set the language the user will speak in. If this method is not called, defaults to 'en-US'. + * + * @param {string} lang + * @see [Languages](https://github.com/TalAter/annyang/blob/master/docs/FAQ.md#what-languages-are-supported) + */ + setLanguage(lang: string): void; + + /** + * Add commands that annyang will respond to. Similar in syntax to init(), but doesn't remove existing commands. + * + * #### Examples: + * ````javascript + * var commands = {'hello :name': helloFunction, 'howdy': helloFunction}; + * var commands2 = {'hi': helloFunction}; + * + * annyang.addCommands(commands); + * annyang.addCommands(commands2); + * // annyang will now listen to all three commands + * ```` + * + * @param {CommandOption} commands + */ + addCommands(commands: CommandOption): void; + + /** + * Removes all existing commands or a specific command + * #### Examples: + * ````javascript + * var commands : annyang.CommandOption = {'hello': helloFunction, 'howdy': helloFunction, 'hi': helloFunction}; + * + * // Don't respond to hello + * annyang.removeCommands('hello'); + * + * // Remove all existing commands + * annyang.removeCommands(); + * ```` + * @param {string} command + */ + removeCommands(command?: string): void; + + /** + * Removes a list of commands + * #### Examples: + * ````javascript + * var commands : annyang.CommandOption = {'hello': helloFunction, 'howdy': helloFunction, 'hi': helloFunction}; + * // Add some commands + * annyang.addCommands(commands); + * // Don't respond to howdy or hi + * annyang.removeCommands(['howdy', 'hi']); + * ```` + * + * @param {string[]} command + */ + removeCommands(command: string[]): void; + + /** + * @param {Events} event + * @param {(userSaid : string, commandText : string, results : string[]) => void} callback + * @param {*} [context] + */ + addCallback(event: Events, callback: (userSaid?: string, commandText?: string, results?: string[]) => void, context?: any): void; + + /** + * @param {Events} [event] + * @param {Function} [callback] + */ + removeCallback(event?: Events, callback?: (userSaid: string, commandText: string, results: string[]) => void): void; + + /** + * Returns true if speech recognition is currently on. + * Returns false if speech recognition is off or annyang is paused. + * + * @returns {boolean} + */ + isListening(): boolean; + + /** + * Returns the instance of the browser's SpeechRecognition object used by annyang. + * Useful in case you want direct access to the browser's Speech Recognition engine. + * + * @returns {*} + */ + getSpeechRecognizer(): any; + + /** + * Simulate speech being recognized. This will trigger the same events and behavior as when the Speech Recognition + * detects speech. + * + * Can accept either a string containing a single sentence, or an array containing multiple sentences to be checked + * in order until one of them matches a command (similar to the way Speech Recognition Alternatives are parsed) + * + * #### Examples: + * ````javascript + * annyang.trigger('Time for some thrilling heroics'); + * annyang.trigger( + * ['Time for some thrilling heroics', 'Time for some thrilling aerobics'] + * ); + * ```` + * + * @param {string} command + */ + trigger(command: string | string[]): void; +} diff --git a/types/annyang/tsconfig.json b/types/annyang/tsconfig.json new file mode 100644 index 0000000000..f54c7cd18c --- /dev/null +++ b/types/annyang/tsconfig.json @@ -0,0 +1,22 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": [ + "es6" + ], + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "baseUrl": "../", + "typeRoots": [ + "../" + ], + "types": [], + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "index.d.ts", + "annyang-tests.ts" + ] +} diff --git a/types/annyang/tslint.json b/types/annyang/tslint.json new file mode 100644 index 0000000000..3db14f85ea --- /dev/null +++ b/types/annyang/tslint.json @@ -0,0 +1 @@ +{ "extends": "dtslint/dt.json" }