Update node docs

src/connections/sources/catalog/libraries/server/node/index.md

@@ -15,7 +15,7 @@ All of Segment's server-side libraries are built for high-performance, so you ca
 ## Getting Started
 
 > warning ""
-> Make sure you're using a version of Node that's 16 or higher. 
+> Make sure you're using a version of Node that's 18 or higher. 
 
 1. Run the relevant command to add Segment's Node library module to your `package.json`.
 
@@ -289,25 +289,105 @@ Setting | Details
 
 See the complete `AnalyticsSettings` interface [in the analytics-next repository](https://github.com/segmentio/analytics-next/blob/master/packages/node/src/app/settings.ts){:target="_blank"}.
 
-## Usage in serverless environments
+## Usage in serverless environments and non-node runtimes
+Segment supports a variety of runtimes, including, but not limited to:
+- AWS Lambda
+- Cloudflare Workers
+- Vercel Edge Functions
+- Web Workers / Browser (no device mode destination support)
 
-When calling Track within functions in serverless runtime environments, wrap the call in a `Promise` and `await` it to avoid having the runtime exit or freeze:
+### Usage in AWS Lambda
+- [AWS lambda execution environment](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtime-environment.html){:target="_blank"} is challenging for typically non-response-blocking async activities like tracking or logging, since the runtime terminates or freezes after a response is emitted.
 
-```js
-await new Promise((resolve) =>
-  analytics().track({ ... }, resolve)
-)
+Here is an example of using analytics.js within a handler:
+```ts
+const { Analytics } = require('@segment/analytics-node');
+
+ // Preferable to create a new analytics instance per-invocation. Otherwise, we may get a warning about overlapping flush calls. Also, custom plugins have the potential to be stateful, so we prevent those kind of race conditions.
+const createAnalytics = () => new Analytics({
+      writeKey: '<MY_WRITE_KEY>',
+    }).on('error', console.error);
+
+module.exports.handler = async (event) => {
+  const analytics = createAnalytics()
+
+  analytics.identify({ ... })
+  analytics.track({ ... })
+
+  // ensure analytics events get sent before program exits
+  await analytics.flush()
+
+  return {
+    statusCode: 200,
+  };
+  ....
+};
+```
+
+### Usage in Vercel Edge Functions
+
+```ts
+import { Analytics } from '@segment/analytics-node';
+import { NextRequest, NextResponse } from 'next/server';
+
+const createAnalytics = () => new Analytics({
+  writeKey: '<MY_WRITE_KEY>',
+}).on('error', console.error)
+
+export const config = {
+  runtime: 'edge',
+};
+
+export default async (req: NextRequest) => {
+  const analytics = createAnalytics()
+
+  analytics.identify({ ... })
+  analytics.track({ ... })
+
+  // ensure analytics events get sent before program exits
+  await analytics.flush()
+
+  return NextResponse.json({ ... })
+};
 ```
 
-See the complete documentation on [Usage in AWS Lambda](https://github.com/segmentio/analytics-next/blob/master/packages/node/README.md#usage-in-aws-lambda){:target="_blank"}, [Usage in Vercel Edge Functions](https://github.com/segmentio/analytics-next/blob/master/packages/node/README.md#usage-in-vercel-edge-functions){:target="_blank"}, and [Usage in Cloudflare Workers](https://github.com/segmentio/analytics-next/blob/master/packages/node/README.md#usage-in-cloudflare-workers){:target="_blank"}
+### Usage in Cloudflare Workers
+
+```ts
+import { Analytics, Context } from '@segment/analytics-node';
+
+
+const createAnalytics = () => new Analytics({
+  writeKey: '<MY_WRITE_KEY>',
+}).on('error', console.error);
+
+export default {
+  async fetch(
+    request: Request,
+    env: Env,
+    ctx: ExecutionContext
+  ): Promise<Response> {
+    const analytics = createAnalytics()
+
+    analytics.identify({ ... })
+    analytics.track({ ... })
+
+    // ensure analytics events get sent before program exits
+    await analytics.flush()
+
+    return new Response(...)
+  },
+};
+
+```
 
 ## Graceful shutdown
-Avoid losing events after shutting down your console. Call `.closeAndFlush()` to stop collecting new events and flush all existing events. If a callback on an event call is included, this also waits for all callbacks to be called, and any of their subsequent promises to be resolved.
+Avoid losing events after shutting down your console. Call `.flush({ close: true })` to stop collecting new events and flush all existing events. If a callback on an event call is included, this also waits for all callbacks to be called, and any of their subsequent promises to be resolved.
 
 ```javascript
-await analytics.closeAndFlush()
+await analytics.flush({ close: true })
 // or
-await analytics.closeAndFlush({ timeout: 5000 }) // force resolve after 5000ms
+await analytics.flush({ close: true, timeout: 5000 }) // force resolve after 5000ms
 ```
 
 Here's an example of how to use graceful shutdown:
@@ -316,7 +396,7 @@ const app = express()
 const server = app.listen(3000)
 
 const onExit = async () => {
-  await analytics.closeAndFlush()
+  await analytics.flush({ close: true })
   server.close(() => {
     console.log("Gracefully closing server...")
     process.exit()
@@ -326,15 +406,15 @@ const onExit = async () => {
 ```
 
 ### Collect unflushed events 
-If you need to preserve all of your events in the instance of a forced timeout, even ones that came in after analytics.closeAndFlush() was called, you can still collect those events by using:
+If you need to preserve all of your events in the instance of a forced timeout, even ones that came in after analytics.flush({ close: true }) was called, you can still collect those events by using:
 
 ```javascript
 const unflushedEvents = []
 
 analytics.on('call_after_close', (event) => unflushedEvents.push(events))
-await analytics.closeAndFlush()
+await analytics.flush({ close: true })
 
-console.log(unflushedEvents) // all events that came in after closeAndFlush was called
+console.log(unflushedEvents) // all events that came in after flush was called
 ```
 
 ## Regional configuration
@@ -362,22 +442,17 @@ analytics.on('error', (err) => console.error(err))
 
 
 ### Event emitter interface
-The event emitter interface allows you to track events, like Track and Identify calls, and it calls the function you provided with some arguments upon successful delivery. `error` emits on delivery error. 
-
-```javascript
-analytics.on('error', (err) => console.error(err))
+The event emitter interface allows you to pass a callback which will be invoked whenever a specific emitter event occurs in your app, such as when a certain method call is made.
 
-analytics.on('identify', (ctx) => console.log(ctx))
+For example:
 
+```javascript
 analytics.on('track', (ctx) => console.log(ctx))
-```
-
-Use the emitter to log all HTTP Requests.
+analytics.on('error', (err) => console.error(err))
 
-  ```javascript
-  analytics.on('http_request', (event) => console.log(event))
 
-  // when triggered, emits an event of the shape:
+// when triggered, emits an event of the shape:
+analytics.on('http_request', (event) => console.log(event))
   {
       url: 'https://api.segment.io/v1/batch',
       method: 'POST',
@@ -388,32 +463,43 @@ Use the emitter to log all HTTP Requests.
       body: '...',
   }
   ```
+
+  ### Emitter Types
 
+  The following table documents all the emitter types available in the Analytics Node.js library:
 
-## Plugin architecture
-When you develop in [Analytics.js 2.0](/docs/connections/sources/catalog/libraries/website/javascript/), the plugins you write can improve functionality, enrich data, and control the flow and delivery of events. From modifying event payloads to changing analytics functionality, plugins help to speed up the process of getting things done.
+  | Emitter Type      | Description                                                                 |
+  |-------------------|-----------------------------------------------------------------------------|
+  | `error`           | Emitted when there is an error after SDK initialization.                       |
+  | `identify`        | Emitted when an Identify call is made.
+  | `track`           | Emitted when a Track call is made.
+  | `page`            | Emitted when a Page call is made.
+  | `group`           | Emitted when a Group call is made.
+  | `alias`           | Emitted when an Alias call is made.
+  | `flush`            | Emitted after a batch is flushed.
+  | `http_request`    | Emitted when an HTTP request is made.                                        |
+  | `register`        | Emitted when a plugin is registered
+  | `call_after_close`| Emitted when an event is received after the flush with `{ close: true }`.   |
 
-Though middlewares function the same as plugins, it's best to use plugins as they are easier to implement and are more testable.
+  These emitters allow you to hook into various stages of the event lifecycle and handle them accordingly.
 
-### Plugin categories
-Plugins are bound by Analytics.js 2.0 which handles operations such as observability, retries, and error handling. There are two different categories of plugins:
-* **Critical Plugins**: Analytics.js expects this plugin to be loaded before starting event delivery. Failure to load a critical plugin halts event delivery. Use this category sparingly, and only for plugins that are critical to your tracking.
-* **Non-critical Plugins**: Analytics.js can start event delivery before this plugin finishes loading. This means your plugin can fail to load independently from all other plugins. For example, every Analytics.js destination is a non-critical plugin. This makes it possible for Analytics.js to continue working if a partner destination fails to load, or if users have ad blockers turned on that are targeting specific destinations.
 
-> info ""
-> Non-critical plugins are only non-critical from a loading standpoint. For example, if the `before` plugin crashes, this can still halt the event delivery pipeline.
+## Plugin architecture
+The plugins you write can improve functionality, enrich data, and control the flow and delivery of events. From modifying event payloads to changing analytics functionality, plugins help to speed up the process of getting things done.
+
 
-Non-critical plugins run through a timeline that executes in order of insertion based on the entry type. Segment has these five entry types of non-critical plugins:
+### Plugin categories
+Segment has these five entry types of plugins:
 
-| Type | Details
------- | --------              
-| `before`      | Executes before event processing begins. These are plugins that run before any other plugins run. <br><br>For example, validating events before passing them along to other plugins. A failure here could halt the event pipeline.  
-| `enrichment`  | Executes as the first level of event processing. These plugins modify an event. 
-| `destination` | Executes as events begin to pass off to destinations. <br><br> This doesn't modify the event outside of the specific destination, and failure doesn't halt the execution.  
-| `after`       | Executes after all event processing completes. You can use this to perform cleanup operations. <br><br>An example of this is the [Segment.io Plugin](https://github.com/segmentio/analytics-next/blob/master/packages/browser/src/plugins/segmentio/index.ts){:target="_blank"} which waits for destinations to succeed or fail so it can send it observability metrics.  
-| `utility`     | Executes once during the bootstrap, to give you an outlet to make any modifications as to how Analytics.js works internally. This allows you to augment Analytics.js functionality.                                                                                                                                                                                
+| Type          | Details                                                                                                                                                                                                                                                                                                                                                                                                                   
+| ------------- | ------------- |
+| `before`      | Executes before event processing begins. These are plugins that run before any other plugins run. Thrown errors here can block the event pipeline. Source middleware added using `addSourceMiddleware` is treated as a `before` plugin. No events send to destinations until `.load()` method is resolved. |
+| `enrichment`  | Executes as the first level of event processing. These plugins modify an event. Thrown errors here can block the event pipeline. No events send to destinations until `.load()` method is resolved. |
+| `destination` | Executes as events begin to pass off to destinations. Segment.io is implemented as a destination plugin. Thrown errors here will _not_ block the event pipeline. |
+| `after`       | Executes after all event processing completes. You can use this to perform cleanup operations. |
+| `utility`     | Executes _only once_ during the bootstrap. Gives you access to the analytics instance using the plugin's `load()` method. This doesn't allow you to modify events. |
 
-### Example plugins
+### Example plugin
 Here's an example of a plugin that converts all track event names to lowercase before the event goes through the rest of the pipeline:
 
 ```js
@@ -430,49 +516,8 @@ export const lowercase: Plugin = {
     return ctx
   }
 }
-
-const identityStitching = () => {
-  let user
-
-  const identity = {
-    // Identifies your plugin in the Plugins stack.
-    // Access `window.analytics.queue.plugins` to see the full list of plugins
-    name: 'Identity Stitching',
-    // Defines where in the event timeline a plugin should run
-    type: 'enrichment',
-    version: '0.1.0',
-
-    // Used to signal that a plugin has been property loaded
-    isLoaded: () => user !== undefined,
-
-    // Applies the plugin code to every `identify` call in Analytics.js
-    // You can override any of the existing types in the Segment Spec.
-    async identify(ctx) {
-      // Request some extra info to enrich your `identify` events from
-      // an external API.
-      const req = await fetch(
-        `https://jsonplaceholder.typicode.com/users/${ctx.event.userId}`
-      )
-      const userReq = await req.json()
-
-      // ctx.updateEvent can be used to update deeply nested properties
-      // in your events. It's a safe way to change events as it'll
-      //  create any missing objects and properties you may require.
-      ctx.updateEvent('traits.custom', userReq)
-      user.traits(userReq)
-
-      // Every plugin must return a `ctx` object, so that the event
-      // timeline can continue processing.
-      return ctx
-    },
-  }
-
-  return identity
-}
 ```
 
-You can view Segment's [existing plugins](https://github.com/segmentio/analytics-next/tree/master/packages/browser/src/plugins){:target="_blank"} to see more examples.
-
 ### Register a plugin
 Registering plugins enable you to modify your analytics implementation to best fit your needs. You can register a plugin using this:
 

src/connections/sources/catalog/libraries/server/node/migration.md

@@ -32,14 +32,14 @@ If you're using the [classic version of Analytics Node.js](/docs/connections/sou
 
      <br> Before:
     ```javascript  
-    await analytics.flush(function(err, batch) {
+    await analytics.flush((err, batch) => {
         console.log('Flushed, and now this program can exit!');
     });
     ```
 
     After:
     ```javascript
-    await analytics.closeAndFlush()
+    await analytics.flush({ close: true })
     ```
 
 ### Key differences between the classic and updated version