docs: Updating docs

algorandfoundation · Dec 10, 2023 · fa1f181 · fa1f181
1 parent e7e75ad
commit fa1f181
Show file tree

Hide file tree

Showing 4 changed files with 89 additions and 37 deletions.
diff --git a/docs/code/classes/index.AlgorandSubscriber.md b/docs/code/classes/index.AlgorandSubscriber.md
@@ -18,6 +18,8 @@ Handles the logic for subscribing to the Algorand blockchain and emitting events
 - [algod](index.AlgorandSubscriber.md#algod)
 - [eventEmitter](index.AlgorandSubscriber.md#eventemitter)
 - [indexer](index.AlgorandSubscriber.md#indexer)
+- [startPromise](index.AlgorandSubscriber.md#startpromise)
+- [started](index.AlgorandSubscriber.md#started)
 - [subscription](index.AlgorandSubscriber.md#subscription)
 
 ### Methods
@@ -50,7 +52,7 @@ Create a new `AlgorandSubscriber`.
 
 #### Defined in
 
-[subscriber.ts:23](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L23)
+[subscriber.ts:27](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L27)
 
 ## Properties
 
@@ -60,7 +62,7 @@ Create a new `AlgorandSubscriber`.
 
 #### Defined in
 
-[subscriber.ts:14](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L14)
+[subscriber.ts:16](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L16)
 
 ___
 
@@ -70,7 +72,7 @@ ___
 
 #### Defined in
 
-[subscriber.ts:11](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L11)
+[subscriber.ts:13](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L13)
 
 ___
 
@@ -80,7 +82,7 @@ ___
 
 #### Defined in
 
-[subscriber.ts:15](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L15)
+[subscriber.ts:17](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L17)
 
 ___
 
@@ -90,7 +92,27 @@ ___
 
 #### Defined in
 
-[subscriber.ts:12](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L12)
+[subscriber.ts:14](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L14)
+
+___
+
+### startPromise
+
+• `Private` **startPromise**: `undefined` \| `Promise`\<`void`\>
+
+#### Defined in
+
+[subscriber.ts:19](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L19)
+
+___
+
+### started
+
+• `Private` **started**: `boolean` = `false`
+
+#### Defined in
+
+[subscriber.ts:18](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L18)
 
 ___
 
@@ -100,13 +122,13 @@ ___
 
 #### Defined in
 
-[subscriber.ts:13](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L13)
+[subscriber.ts:15](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L15)
 
 ## Methods
 
 ### on
 
-▸ **on**\<`T`\>(`eventName`, `listener`): `void`
+▸ **on**\<`T`\>(`eventName`, `listener`): [`AlgorandSubscriber`](index.AlgorandSubscriber.md)
 
 Register an event handler to run on every instance the given event name.
 
@@ -127,17 +149,19 @@ The listener can be async and it will be awaited if so.
 
 #### Returns
 
-`void`
+[`AlgorandSubscriber`](index.AlgorandSubscriber.md)
+
+The subscriber so `on`/`onBatch` calls can be chained
 
 #### Defined in
 
-[subscriber.ts:106](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L106)
+[subscriber.ts:145](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L145)
 
 ___
 
 ### onBatch
 
-▸ **onBatch**\<`T`\>(`eventName`, `listener`): `void`
+▸ **onBatch**\<`T`\>(`eventName`, `listener`): [`AlgorandSubscriber`](index.AlgorandSubscriber.md)
 
 Register an event handler to run on all instances of the given event name
 for each subscription poll.
@@ -162,17 +186,19 @@ The listener can be async and it will be awaited if so.
 
 #### Returns
 
-`void`
+[`AlgorandSubscriber`](index.AlgorandSubscriber.md)
+
+The subscriber so `on`/`onBatch` calls can be chained
 
 #### Defined in
 
-[subscriber.ts:121](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L121)
+[subscriber.ts:162](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L162)
 
 ___
 
 ### pollOnce
 
-▸ **pollOnce**(): `Promise`\<`void`\>
+▸ **pollOnce**(): `Promise`\<[`TransactionSubscriptionResult`](../interfaces/types_subscription.TransactionSubscriptionResult.md)\>
 
 Execute a single subscription poll.
 
@@ -181,48 +207,61 @@ triggered by a recurring schedule / cron.
 
 #### Returns
 
-`Promise`\<`void`\>
+`Promise`\<[`TransactionSubscriptionResult`](../interfaces/types_subscription.TransactionSubscriptionResult.md)\>
+
+The poll result
 
 #### Defined in
 
-[subscriber.ts:46](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L46)
+[subscriber.ts:51](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L51)
 
 ___
 
 ### start
 
-▸ **start**(): `void`
+▸ **start**(`inspect?`, `suppressLog?`): `void`
 
 Start the subscriber in a loop until `stop` is called.
 
 This is useful when running in the context of a long-running process / container.
 
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `inspect?` | (`pollResult`: [`TransactionSubscriptionResult`](../interfaces/types_subscription.TransactionSubscriptionResult.md)) => `void` | A function that is called for each poll so the inner workings can be inspected / logged / etc. |
+| `suppressLog?` | `boolean` | - |
+
 #### Returns
 
 `void`
 
+An object that contains a promise you can wait for after calling stop
+
 #### Defined in
 
-[subscriber.ts:81](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L81)
+[subscriber.ts:88](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L88)
 
 ___
 
 ### stop
 
-▸ **stop**(`reason`): `void`
+▸ **stop**(`reason`): `Promise`\<`void`\>
 
 Stops the subscriber if previously started via `start`.
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `reason` | `unknown` |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `reason` | `unknown` | The reason the subscriber is being stopped |
 
 #### Returns
 
-`void`
+`Promise`\<`void`\>
+
+A promise that can be awaited to ensure the subscriber has finished stopping
 
 #### Defined in
 
-[subscriber.ts:95](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L95)
+[subscriber.ts:131](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L131)
diff --git a/docs/code/interfaces/types_subscription.SubscriptionConfig.md b/docs/code/interfaces/types_subscription.SubscriptionConfig.md
@@ -14,6 +14,7 @@ Configuration for a subscription
 - [frequencyInSeconds](types_subscription.SubscriptionConfig.md#frequencyinseconds)
 - [maxRoundsToSync](types_subscription.SubscriptionConfig.md#maxroundstosync)
 - [syncBehaviour](types_subscription.SubscriptionConfig.md#syncbehaviour)
+- [waitForBlockWhenAtTip](types_subscription.SubscriptionConfig.md#waitforblockwhenattip)
 - [watermarkPersistence](types_subscription.SubscriptionConfig.md#watermarkpersistence)
 
 ## Properties
@@ -26,15 +27,15 @@ The set of events to subscribe to / emit
 
 #### Defined in
 
-[types/subscription.ts:106](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L106)
+[types/subscription.ts:108](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L108)
 
 ___
 
 ### frequencyInSeconds
 
-• **frequencyInSeconds**: `number`
+• `Optional` **frequencyInSeconds**: `number`
 
-The frequency to poll for new blocks in seconds
+The frequency to poll for new blocks in seconds; defaults to 1s
 
 #### Defined in
 
@@ -44,13 +45,13 @@ ___
 
 ### maxRoundsToSync
 
-• **maxRoundsToSync**: `number`
+• `Optional` **maxRoundsToSync**: `number`
 
-The maximum number of rounds to sync at a time.
+The maximum number of rounds to sync at a time; defaults to 500
 
 #### Defined in
 
-[types/subscription.ts:104](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L104)
+[types/subscription.ts:106](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L106)
 
 ___
 
@@ -59,7 +60,7 @@ ___
 • **syncBehaviour**: ``"skip-sync-newest"`` \| ``"sync-oldest"`` \| ``"sync-oldest-start-now"`` \| ``"catchup-with-indexer"``
 
 The behaviour when the number of rounds to sync is greater than `maxRoundsToSync`:
- * `skip-sync-newest`: Discard old rounds
+ * `skip-sync-newest`: Discard old rounds.
  * `sync-oldest`: Sync from the oldest records up to `maxRoundsToSync` rounds.
 
    **Note:** will be slow to catch up if sync is significantly behind the tip of the chain
@@ -70,7 +71,19 @@ The behaviour when the number of rounds to sync is greater than `maxRoundsToSync
 
 #### Defined in
 
-[types/subscription.ts:117](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L117)
+[types/subscription.ts:119](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L119)
+
+___
+
+### waitForBlockWhenAtTip
+
+• `Optional` **waitForBlockWhenAtTip**: `boolean`
+
+Whether to wait via algod `/status/wait-for-block-after` endpoint when at the tip of the chain; reduces latency of subscription
+
+#### Defined in
+
+[types/subscription.ts:104](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L104)
 
 ___
 
@@ -79,7 +92,7 @@ ___
 • **watermarkPersistence**: `Object`
 
 Methods to retrieve and persist the current watermark so syncing is resilient and maintains
-its position in the chain.
+its position in the chain
 
 #### Type declaration
 
@@ -90,4 +103,4 @@ its position in the chain.
 
 #### Defined in
 
-[types/subscription.ts:120](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L120)
+[types/subscription.ts:122](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L122)
diff --git a/docs/code/interfaces/types_subscription.SubscriptionConfigEvent.md b/docs/code/interfaces/types_subscription.SubscriptionConfigEvent.md
@@ -30,7 +30,7 @@ Name / identifier to uniquely describe the event
 
 #### Defined in
 
-[types/subscription.ts:131](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L131)
+[types/subscription.ts:133](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L133)
 
 ___
 
@@ -42,7 +42,7 @@ The transaction filter that determines if the event has occurred
 
 #### Defined in
 
-[types/subscription.ts:133](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L133)
+[types/subscription.ts:135](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L135)
 
 ___
 
@@ -70,4 +70,4 @@ If not specified, then the event will receive a `TransactionResult`.
 
 #### Defined in
 
-[types/subscription.ts:138](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L138)
+[types/subscription.ts:140](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L140)
diff --git a/docs/code/modules/types_subscription.md b/docs/code/modules/types_subscription.md
@@ -45,4 +45,4 @@
 
 #### Defined in
 
-[types/subscription.ts:141](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L141)
+[types/subscription.ts:143](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L143)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -45,4 +45,4 @@

		#### Defined in

		[types/subscription.ts:141](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L141)
		[types/subscription.ts:143](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L143)