fix(temporal-set): Code did not match spec

languages/javascript/src/shared/TemporalSet/index.mjs

@@ -29,7 +29,7 @@ function stopSession(module, method) {
     delete sessions[module.toLowerCase() + '.' + method]
 }
 
-function start(module, method, addName, removeName, params, add, remove, transforms) {
+function start(module, method, addName, removeName, params, add, remove, timeout, transforms) {
     let session = getSession(module, method)
 
     if (!eventEmitterInitialized) {
@@ -44,8 +44,8 @@ function start(module, method, addName, removeName, params, add, remove, transfo
         session = startSession(module, method)
     }
 
-    if (!add) {
-        throw `Error: ${module}.${method} requires at least one callback because results may be asynchronous.`
+    if (add && timeout) {
+        throw `Error: ${module}.${method} requires either a timeout, or at least one callback because results may be asynchronous.`
     }
 
     const requests = [
@@ -87,7 +87,7 @@ function start(module, method, addName, removeName, params, add, remove, transfo
     session.removeName = removeName
 
     results[0].promise.then( items => {
-        items && items.forEach(item => add(item))
+        add && items && items.forEach(item => add(item))
     })
 
     results[1].promise.then( id => {
@@ -113,42 +113,54 @@ function start(module, method, addName, removeName, params, add, remove, transfo
         })
     }
 
-    return {
-        stop: () => {
-            const requests = [
-                {
-                    module: module,
-                    method: `stop${method.charAt(0).toUpperCase() + method.substr(1)}`,
-                    params: {
-                        correlationId: session.id
-                    }
-                },
-                {
-                    module: module,
-                    method: addName,
-                    params: {
-                        listen: false
+    if (add) {
+        return {
+            stop: () => {
+                const requests = [
+                    {
+                        module: module,
+                        method: `stop${method.charAt(0).toUpperCase() + method.substr(1)}`,
+                        params: {
+                            correlationId: session.id
+                        }
+                    },
+                    {
+                        module: module,
+                        method: addName,
+                        params: {
+                            listen: false
+                        }
                     }
+                ]
+
+                if (remove) {
+                    requests.push({
+                        module: module,
+                        method: removeName,
+                        params: {
+                            listen: false
+                        }
+                    })
                 }
-            ]
-
-            if (remove) {
-                requests.push({
-                    module: module,
-                    method: removeName,
-                    params: {
-                        listen: false
-                    }
-                })
+                Transport.send(requests)
+                stopSession(module, method)
             }
-            Transport.send(requests)
-            stopSession(module, method)
         }
     }
+    else if (timeout) {
+        return results[0].promise.then(results => {
+            stopSession(module, method)
+            return results.shift()
+        })
+    }
+    else {
+        return results[0].promise.then(results => {
+            stopSession(module, method)
+            return results
+        })
+    }
 }
 
-
-
 export default {
   start: start
 }

languages/javascript/templates/declarations/temporal-set.js

@@ -1,16 +1,28 @@
+interface ${method.item.type}Process {
+   stop(): void
+}
+
   /**
-   * ${method.summary}
+   * Live list: ${method.summary}
    * 
-${method.params.annotations}   * @param {Function} add A method for receiving ${method.item.type} objects as they become available${if.deprecated}
-   * @deprecated ${method.deprecation}
+${method.params.annotations}   * @param {Function} add A method for receiving ${method.item.type} objects as they become available
+   * @param {Function} remove A method for receiving ${method.item.type} objects as they become unavailable
+${if.deprecated}   * @deprecated ${method.deprecation}
 ${end.if.deprecated}   */
-  function ${method.name}(${method.signature.params}${if.context}, ${end.if.context} add: (${method.item}: ${method.item.type}) => void): { stop: () => void }
+  function ${method.name}(${method.signature.params}${if.context}, ${end.if.context} add: (${method.item}: ${method.item.type}) => void, remove: (${method.item}: ${method.item.type}) => void): ${method.item.type}Process
 
   /**
-   * ${method.summary}
+   * First match: ${method.summary}
    * 
-${method.params.annotations}   * @param {Function} add A method for receiving ${method.item.type} objects as they become available
-   * @param {Function} remove A method for receiving ${method.item.type} objects as they become unavailable
+${method.params.annotations}   * @param {Function} timeout How long, in ms, to wait for a match
+${if.deprecated}   * @deprecated ${method.deprecation}
+${end.if.deprecated}   */
+function ${method.name}(${method.signature.params}${if.context}, ${end.if.context} timeout: number): Promise<${method.item.type}>
+
+  /**
+   * Known values w/out updates: ${method.summary}
+   * 
+${method.params.annotations}
 ${if.deprecated}   * @deprecated ${method.deprecation}
 ${end.if.deprecated}   */
-  function ${method.name}(${method.signature.params}${if.context}, ${end.if.context} add: (${method.item}: ${method.item.type}) => void, remove: (${method.item}: ${method.item.type}) => void): { stop: () => void }
+function ${method.name}(${method.signature.params}): Promise<${method.item.type}[]>

languages/javascript/templates/examples/temporal-set.md

@@ -1,6 +1,6 @@
 import { ${module} } from '${package.name}'
 
-const process = ${module}.${method.name}(function(${example.params}${if.params},${end.if.params}
+const process = ${module}.${method.name}(${example.params}${if.params},${end.if.params}
     ${method.item} => {
         console.log('Added to temporal set:')
         console.dir(${method.item})
@@ -10,4 +10,12 @@ const process = ${module}.${method.name}(function(${example.params}${if.params},
         console.dir(${method.item})
     })
 
-setTimeout( () => process.stop(), 10000)
+setTimeout( () => process.stop(), 10000)
+```
+
+Request only the first match:
+
+```javascript
+import { ${module} } from '${package.name}'
+
+const ${method.item} = await ${module}.${method.name}(${example.params}${if.params}, ${end.if.params}1000)

languages/javascript/templates/methods/temporal-set.js

@@ -1,14 +1,17 @@
 function ${method.name}(...args) {
-    let add, remove
+    let add, remove, timeout
     if (typeof args[args.length-1] === 'function' && typeof args[args.length-2] === 'function') {
         remove = args.pop()
         add = args.pop()
     }
     else if (typeof args[args.length-1] === 'function') {
         add = args.pop()
     }
+    else if (typeof args[args.length-1] === 'number') {
+        timeout = args.pop()
+    }
 
     const transforms = ${method.transforms}
 
-    return TemporalSet.start('${info.title}', '${method.name}', '${method.temporalset.add}', '${method.temporalset.remove}', arguments, add, remove, transforms)
+    return TemporalSet.start('${info.title}', '${method.name}', '${method.temporalset.add}', '${method.temporalset.remove}', args, add, remove, timeout, transforms)
 }

languages/markdown/templates/methods/temporal-set.md

@@ -3,7 +3,7 @@
 ${method.summary}
 
 ```typescript
-function ${method.name}(${method.signature.params}${if.context}, ${end.if.context}add: (${method.item}: ${method.item.type}) => void, remove?: (${method.item}: ${method.item.type}) => void ): Promise<Process>
+function ${method.name}(${method.signature.params}${if.context}, ${end.if.context}add: (${method.item}: ${method.item.type}) => void, remove?: (${method.item}: ${method.item.type}) => void ): ${method.item.type}Process
 ```
 
 Parameters:
@@ -13,14 +13,32 @@ Parameters:
 ${method.params.table.rows}| add                    | `function`           | true                     | Callback to pass any `${method.item.type}` objects to, as they become available |
 | remove                 | `function`           | false                    | Callback to pass any `${method.item.type}` objects to, as they become unavailable |
 
-Promise resolution:
+Returns:
 
 ```typescript
-interface Process {
+interface ${method.item.type}Process {
     stop(): void // Stops updating this temporal set with ${method.item.type} objects
 }
 ```
 
+Additionally, the `${method.name}` method may be called witha `timeout` parameter to find the first match and automatically stop scanning:
+
+```typescript
+function ${method.name}(${method.signature.params}${if.context}, ${end.if.context}timeout: number): Promise<${method.item.type}>
+```
+
+Parameters:
+
+| Param                  | Type                 | Required                 | Summary                 |
+| ---------------------- | -------------------- | ------------------------ | ----------------------- |
+${method.params.table.rows}| timeout                    | `number`           | true                     | How long to wait, in ms, for a match. |
+
+Promise resolution:
+
+```typescript
+${method.item.type}
+```
+
 #### Examples
 
 ${method.examples}