docs: README and doc string fixes (#321)

*Issue #, if available:* #246

*Description of changes:* This PR fixes inconsistent and confusing
terminology in the documentation for map() and parallel() operations,
along with minor capitalization corrections.

By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice.

---------

Signed-off-by: Michael Gasch <15986659+embano1@users.noreply.github.com>

Author: embano1

package.json

@@ -1,7 +1,7 @@
 {
   "name": "aws-durable-execution-sdk-js",
   "version": "0.0.1",
-  "description": "Lambda Durable Functions SDK, Testing SDK and fully functional examples",
+  "description": "Lambda durable functions SDK, Testing SDK and fully functional examples",
   "workspaces": [
     "packages/*"
   ],

packages/aws-durable-execution-sdk-js-eslint-plugin/README.md

@@ -1,6 +1,6 @@
 # @aws/durable-execution-sdk-js-eslint-plugin
 
-ESLint plugin for AWS Lambda Durable Functions best practices.
+ESLint plugin for AWS Lambda durable functions best practices.
 
 ## Installation
 
@@ -145,7 +145,7 @@ The plugin detects these durable operations:
 
 ### No Nested Durable Operations
 
-Nesting durable operations with the same context object can cause runtime errors and unexpected behavior in AWS Lambda Durable Functions. This rule helps catch these issues at development time.
+Nesting durable operations with the same context object can cause runtime errors and unexpected behavior in AWS Lambda durable functions. This rule helps catch these issues at development time.
 
 ### No Closure in Durable Operations
 

packages/aws-durable-execution-sdk-js-eslint-plugin/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aws/durable-execution-sdk-js-eslint-plugin",
   "version": "1.0.0",
-  "description": "ESLint plugin for AWS Lambda Durable Functions best practices",
+  "description": "ESLint plugin for AWS Lambda durable functions best practices",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "engines": {

packages/aws-durable-execution-sdk-js/README.md

@@ -182,7 +182,7 @@ const result = await context.waitForCallback(
 
 ### Map
 
-Process arrays with concurrency control:
+Process arrays of items, applying durable operations to each with concurrency control:
 
 ```typescript
 const results = await context.map(
@@ -208,9 +208,11 @@ console.log(
 results.throwIfError(); // Throws if any failures
 ```
 
+**Note**: `map()` executes durable operations (steps, waits, etc.) within the same Lambda invocation using child contexts for isolation. It does not spawn separate Lambda functions.
+
 ### Parallel
 
-Execute multiple functions in parallel:
+Execute multiple branches with durable operations in parallel:
 
 ```typescript
 const results = await context.parallel(
@@ -227,6 +229,8 @@ const results = await context.parallel(
 );
 ```
 
+**Note**: `parallel()` executes durable operations within the same Lambda invocation. Each branch runs in its own child context with isolated state tracking.
+
 ### Concurrent Execution
 
 Fine-grained control over concurrent operations:

packages/aws-durable-execution-sdk-js/src/types/durable-context.ts

@@ -401,7 +401,7 @@ export interface DurableContext<Logger extends DurableLogger = DurableLogger> {
   ): DurablePromise<T>;
 
   /**
-   * Maps over an array of items with a function, executing in parallel with optional concurrency control
+   * Processes an array of items, applying durable operations to each with optional concurrency control
    * @param name - Step name for tracking and debugging
    * @param items - Array of items to process
    * @param mapFunc - Function to apply to each item (context, item, index, array) =\> Promise\<TOutput\>
@@ -427,7 +427,7 @@ export interface DurableContext<Logger extends DurableLogger = DurableLogger> {
   ): DurablePromise<BatchResult<TOutput>>;
 
   /**
-   * Maps over an array of items with a function, executing in parallel with optional concurrency control
+   * Processes an array of items, applying durable operations to each with optional concurrency control
    * @param items - Array of items to process
    * @param mapFunc - Function to apply to each item (context, item, index, array) =\> Promise\<TOutput\>
    * @param config - Optional configuration for concurrency and completion behavior
@@ -446,7 +446,7 @@ export interface DurableContext<Logger extends DurableLogger = DurableLogger> {
   ): DurablePromise<BatchResult<TOutput>>;
 
   /**
-   * Executes multiple functions in parallel with optional concurrency control
+   * Executes multiple branches with durable operations in parallel with optional concurrency control
    * @param name - Step name for tracking and debugging
    * @param branches - Array of functions or named branches to execute in parallel (all must return same type)
    * @param config - Optional configuration for concurrency and completion behavior
@@ -469,7 +469,7 @@ export interface DurableContext<Logger extends DurableLogger = DurableLogger> {
   ): DurablePromise<BatchResult<T>>;
 
   /**
-   * Executes multiple functions in parallel with optional concurrency control
+   * Executes multiple branches with durable operations in parallel with optional concurrency control
    * @param branches - Array of functions or named branches to execute in parallel (all must return same type)
    * @param config - Optional configuration for concurrency and completion behavior
    * @example
@@ -487,7 +487,7 @@ export interface DurableContext<Logger extends DurableLogger = DurableLogger> {
   ): DurablePromise<BatchResult<T>>;
 
   /**
-   * Executes multiple functions in parallel with optional concurrency control
+   * Executes multiple branches with durable operations in parallel with optional concurrency control
    *
    * @remarks
    * This overload provides automatic type inference for heterogeneous return types.
@@ -528,7 +528,7 @@ export interface DurableContext<Logger extends DurableLogger = DurableLogger> {
   >;
 
   /**
-   * Executes multiple functions in parallel with optional concurrency control
+   * Executes multiple branches with durable operations in parallel with optional concurrency control
    *
    * @remarks
    * This overload provides automatic type inference for heterogeneous return types.