Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documented 13 functions across 6 files #146

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Documented 13 functions across 6 files #146

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f0f7a9f
Added comments to 13 functions across 6 files
komment-ai[bot] Jul 3, 2024
c130a1b
Added comments to 17 functions across 4 files
komment-ai[bot] Jul 8, 2024
f312290
Added comments to 7 functions across 1 file
komment-ai[bot] Aug 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
256 changes: 256 additions & 0 deletions .komment/00000.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,256 @@
[
{
"name": "flatfile.listener.ts",
"path": "packages/listener/src/flatfile.listener.ts",
"content": {
"structured": {
"description": "A Flatfile Listener class that extends an EventHandler and provides various methods for subscribing to events, filtering by namespace, mounting/unmounting event drivers, and forking instances. The listener can be used with different event drivers such as Webhook, Websocket, and Serverless. It utilizes EventFilter and EventDriver classes from external packages.",
"items": [
{
"id": "e7ed0802-de24-5d9d-504e-954945983709",
"ancestors": [],
"description": "Enables subscribing to events within a specific namespace and provides methods for filtering, creating, mounting, and unmounting event listeners using an Event Driver. It facilitates the handling of events by providing a flexible and reusable event listener infrastructure.",
"interfaces": [],
"superclass": "EventHandler",
"is_abstract": false,
"fields": [],
"name": "FlatfileListener",
"location": {
"start": 34,
"insert": 34,
"offset": " ",
"indent": 0,
"comment": null
},
"item_type": "class",
"length": 58,
"docLength": null
},
{
"id": "3c8f8688-6f4f-a7ad-0e45-2a36aac3ed9d",
"ancestors": [
"e7ed0802-de24-5d9d-504e-954945983709"
],
"description": "Filters an array-like object using a callback function and returns the result, passing two parameters: an array of strings representing namespaces and an optional callback function.",
"params": [
{
"name": "namespaces",
"default_value": null,
"optional": false,
"type_name": "string | string[]",
"description": "Used for filtering purposes."
}
],
"returns": {
"type_name": "Array<this>",
"description": "A filtered array of objects based on the given `namespaces` and callback function `cb`."
},
"usage": {
"language": "typescript",
"code": "const listener = FlatfileListener.create(() => {\n listener.namespace(['namespace1', 'namespace2'], (client) => {\n // namespace specific code\n });\n});\n",
"description": ""
},
"name": "namespace",
"location": {
"start": 41,
"insert": 35,
"offset": " ",
"indent": 2,
"comment": {
"start": 34,
"end": 40
}
},
"item_type": "function",
"length": 3,
"docLength": 6
},
{
"id": "3ef1687e-8061-0787-394e-5c8c677208f3",
"ancestors": [
"e7ed0802-de24-5d9d-504e-954945983709"
],
"description": "Creates an instance of the same class with a given `EventFilter`, adds it as a node, and optionally calls a callback function with the created node as an argument. The method returns the created client instance.",
"params": [
{
"name": "filter",
"default_value": null,
"optional": false,
"type_name": "EventFilter",
"description": "Used to specify filtering criteria."
}
],
"returns": {
"type_name": "this",
"description": "An instance of the class that contains the method."
},
"usage": {
"language": "typescript",
"code": "const flatfileListener = FlatfileListener.create((listener) => {\n listener.namespace('event namespace').filter({ namespaces: ['event namespace'] }, (client) => {\n // Event handling code here\n });\n});\n",
"description": ""
},
"name": "filter",
"location": {
"start": 51,
"insert": 45,
"offset": " ",
"indent": 2,
"comment": {
"start": 44,
"end": 50
}
},
"item_type": "function",
"length": 6,
"docLength": 6
},
{
"id": "9557b21b-b4ac-9cad-b147-589ce839699a",
"ancestors": [
"e7ed0802-de24-5d9d-504e-954945983709"
],
"description": "Generates an instance of itself, calls a provided callback function with this instance as argument, and returns the instance. The type parameter `T` ensures that the method can only be called on constructors of types that extend `FlatfileListener`.",
"params": [
{
"name": "cb",
"default_value": null,
"optional": false,
"type_name": "SubFn<T>",
"description": "Callback function."
}
],
"returns": {
"type_name": "T",
"description": "A constructor of FlatfileListener that has been initialized by calling the callback function with it as an argument."
},
"usage": {
"language": "typescript",
"code": "const listener = FlatfileListener.create((client) => {\n client.namespace('myNamespace')\n})\n",
"description": ""
},
"name": "create",
"location": {
"start": 63,
"insert": 58,
"offset": " ",
"indent": 2,
"comment": {
"start": 57,
"end": 62
}
},
"item_type": "function",
"length": 8,
"docLength": 5
},
{
"id": "574b75f4-4b2d-40bb-8f43-2a7f4690f9ee",
"ancestors": [
"e7ed0802-de24-5d9d-504e-954945983709"
],
"description": "Mounts an event handler for the provided `driver`. It binds the current object (`this`) to the driver's event handling mechanism, allowing it to receive and process events from the driver. The method returns the modified instance of `FlatfileListener`.",
"params": [
{
"name": "driver",
"default_value": null,
"optional": false,
"type_name": "EventDriver",
"description": "Intended to provide event handling capabilities."
}
],
"returns": {
"type_name": "this",
"description": "An instance of the current class. The exact nature and purpose of this object are not specified within the provided code snippet."
},
"usage": {
"language": "typescript",
"code": "const listener = new FlatfileListener();\nlistener.mount(new EventDriver());\n",
"description": "\nMount attaches this client using an acceptable event driver."
},
"name": "mount",
"location": {
"start": 75,
"insert": 72,
"offset": " ",
"indent": 2,
"comment": {
"start": 71,
"end": 74
}
},
"item_type": "function",
"length": 4,
"docLength": 3
},
{
"id": "ff766c70-5ac9-cca1-7e41-e597d6b52449",
"ancestors": [
"e7ed0802-de24-5d9d-504e-954945983709"
],
"description": "Unregisters an event handler from the underlying `EventDriver`. It removes the reference to the listener and returns the instance itself for further method chaining.",
"params": [
{
"name": "driver",
"default_value": null,
"optional": false,
"type_name": "EventDriver",
"description": "Intended to unmount an event handler."
}
],
"returns": {
"type_name": "this",
"description": "A reference to the object on which the function was called."
},
"usage": {
"language": "typescript",
"code": "const flatfileListener = FlatfileListener.create((listener) => {\n listener.namespace('event namespace').on('some event', (data) => {\n // handle some event\n });\n});\nflatfileListener.mount(driver);\n// use the listener\nflatfileListener.unmount(driver);",
"description": ""
},
"name": "unmount",
"location": {
"start": 83,
"insert": 80,
"offset": " ",
"indent": 2,
"comment": {
"start": 79,
"end": 82
}
},
"item_type": "function",
"length": 4,
"docLength": 3
},
{
"id": "3a1bfa77-9468-d9a1-f64b-a623266850a8",
"ancestors": [
"e7ed0802-de24-5d9d-504e-954945983709"
],
"description": "Returns a new instance of `FlatfileListener`. This allows for the creation of multiple instances of the same listener, which can be used to handle different tasks or events independently.",
"params": [],
"returns": {
"type_name": "object",
"description": "An instance of `FlatfileListener`."
},
"usage": {
"language": "typescript",
"code": "const listener = new FlatfileListener()\nlistener.fork().namespace('test', (client) => {\n // Do something with client\n})\n",
"description": "\nMount the returned `FlatfileListener` instance to a driver."
},
"name": "fork",
"location": {
"start": 88,
"insert": 88,
"offset": " ",
"indent": 2,
"comment": null
},
"item_type": "function",
"length": 3,
"docLength": null
}
]
}
}
}
]
15 changes: 15 additions & 0 deletions .komment/komment.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"meta": {
"version": "1",
"updated_at": "2024-08-06T02:44:48.655Z",
"created_at": "2024-08-06T02:44:49.925Z",
"pipelines": [
"b6ae3d16-3a08-4a94-a92c-72af0a5a0a40"
]
},
"lookup": [
[
"packages/listener/src/flatfile.listener.ts"
]
]
}
82 changes: 79 additions & 3 deletions apps/react/app/App.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ import { document } from '@/utils/document'
import { workbook } from '@/utils/workbook'
import { recordHook } from '@flatfile/plugin-record-hook'
import {
attachStyleSheet,
Document,
Sheet,
Space,
Expand All @@ -16,11 +15,20 @@ import {
import { useEffect, useState } from 'react'
import styles from './page.module.css'

attachStyleSheet({ nonce: 'flatfile-abc123' }) // add custom nonce

/**
* @description Generates high-quality documentation for given code by using different
* listeners and plugins to log events and handle submissions, and by creating a
* portal iFrame window that can be opened or closed.
*
* @returns {Component} a React component that renders a portal and various listeners
* for event handling.
*/
const App = () => {
const { open, openPortal, closePortal } = useFlatfile()
const [label, setLabel] = useState('Rock')
/**
* @description Either opens or closes a portal based on the provided `open` state.
*/
const toggleOpen = () => {
open ? closePortal({ reset: false }) : openPortal()
}
Expand Down Expand Up @@ -98,6 +106,27 @@ const App = () => {
}}
>
<Document defaultPage config={document} />
{/**
* @description Generates high-quality documentation for code given to it, including
* information on sheets submitted or recorded hooks.
*
* @param {object} config - Workbook configuration object, which defines various
* properties of the Workbook such as its name, onSubmit event handler, and record
* hooks for each sheet.
*
* @param {`AsyncFunction`.} onSubmit - 2nd sheet's onSubmit callback, which logs
* information to the console when called.
*
* * `onSubmit`: This function takes an argument called `sheet` which is an instance
* of the `Sheet` class.
* * `async`: This indicates that the function returns a promise.
* * `{ console.log('onWorkbookSubmission', sheet ) }`: This line logs a message to
* the console with the `sheet` object as its argument whenever the `onSubmit` function
* is called.
*
* @param {object} onRecordHooks - 2-element array of hook functions that will be
* called for each record when the Sheet is submitted or updated.
*/}
<Workbook
config={{
...workbook,
Expand All @@ -121,6 +150,32 @@ const App = () => {
],
]}
>
{/**
* @description Generates high-quality documentation for code given to it. In this
* case, it creates a new sheet with a name and slug specified, sets an onRecordHook
* to modify record data, and an onSubmit hook to log the submitted sheet information
* to the console.
*
* @param {object} config - configuration for a specific sheet, which includes setting
* the sheet name and overriding certain properties of the `workbook` object.
*
* @param {Anonymous Function.} onRecordHook - 1-time function that gets executed
* after each record is transformed into an Immutable record, resulting in an updated
* Immutable record with modified email property set to 'SHEET 3 RECORDHOOK'.
*
* * `record`: The recorded data in the sheet. It is an object with the following
* structure: `record => { email: string }`.
* * `sheet`: The `Sheet` instance itself, which contains additional metadata and
* configuration options for the sheet.
*
* @param {asynchronous function.} onSubmit - occurrence of a user submitting information
* through the Sheet 3 form, and when it is triggered, it logs an information message
* containing the sheet's data to the console.
*
* * `onSubmit`: A function that gets called when the sheet is submitted. The function
* takes the updated sheet as an argument (`{sheet}`) in the shape of an object
* containing the latest values for each record.
*/}
<Sheet
defaultPage
config={{
Expand All @@ -136,6 +191,27 @@ const App = () => {
console.log('onSubmit from Sheet 3', { sheet })
}}
/>
{/**
* @description Sets up a new Google Sheets spreadsheet with a custom slug, name, and
* hooks for records and submissions.
*
* @param {object} config - configuration for the generated documentation, including
* the slug and name of the new sheet, as well as specifying the hook function for
* recording and submitting records.
*
* @param {Anonymous Function.} onRecordHook - function to execute on each record
* when it is hooked, and in this case, the function modifies the `email` field of
* the record by adding the string " SHEET 4 RECORDHOOK".
*
* * `record`: The updated record that is being hooked on to after being serialized
* and sent to the server for processing. Its value is a ` Record <string, any> `.
* * `set(key: string, value: any)`: A function that updates the specified property
* of the record with the provided value. The keys are assumed to be valid string
* identifiers of properties in a JSON object.
*
* @param {object} onSubmit - sheet that is submitted after a record has been modified
* in the specified hook.
*/}
<Sheet
config={{
...workbook.sheets![0],
Expand Down
Loading