Added examples

Author: robnewton

README.md

@@ -138,9 +138,183 @@ npm run deploy-force 1.0.1
 
 # Using the @hopdrive/package-deploy-scripts integration
 npm run deploy-wrapper  # Uses the wrapper around package-deploy-scripts
-npm run deploy:wrapper  # Uses direct integration with package-deploy-scripts
 ```
 
+During deployment, the `lib/version.js` file is automatically generated using the `genversion` npm package. This file exports the current package version from package.json, making it accessible throughout the codebase.
+
+## Examples
+
+This package includes several example implementations in the `examples` directory:
+
+### 1. Simple Lambda Example
+
+**File:** `examples/simple-lambda-example.js`
+
+A basic example showing how to use the wrapper in a standard AWS Lambda function without any framework dependencies.
+
+### 2. Netlify Function Example
+
+**Files:**
+- JavaScript: `examples/netlify-function-example.js`
+- TypeScript: `examples/netlify-function-example.ts`
+
+Shows how to use the wrapper in a Netlify Function, which runs on AWS Lambda, with database connection handling.
+
+### 3. Local Testing Example
+
+**File:** `examples/local-fallback-example.js`
+
+Demonstrates how to use the wrapper with the fallback timer mode for local development and testing outside of a Lambda environment.
+
+### How to Use These Examples
+
+#### AWS Lambda or Netlify Functions
+
+1. **Install the package:**
+   ```bash
+   npm install @hopdrive/lambda-timeout-wrapper
+   ```
+
+2. **For Netlify Functions:**
+   - Create a `netlify/functions` directory in your project
+   - Copy the example file and customize as needed
+   - Install TypeScript if using the TypeScript example:
+     ```bash
+     npm install --save-dev typescript @netlify/functions
+     ```
+   - Create a `netlify.toml` file to configure function settings:
+     ```toml
+     [build]
+       functions = "netlify/functions"
+
+     [functions]
+       # Extend the timeout to 30 seconds (default is 10)
+       timeout = 30
+     ```
+
+3. **Deploy to AWS or Netlify:**
+   - Follow standard AWS Lambda or Netlify deployment procedures
+   - Your functions will now gracefully handle timeouts
+
+#### Local Testing
+
+1. **Install the package:**
+   ```bash
+   npm install @hopdrive/lambda-timeout-wrapper
+   ```
+
+2. **Run the local example:**
+   ```bash
+   node examples/local-fallback-example.js
+   ```
+
+3. **Customize timeout values:**
+   - Adjust `getRemainingTimeInMillis` to simulate different Lambda timeouts
+   - Modify the simulated task duration to test timeout behavior
+
+### Key Concepts Demonstrated
+
+#### 1. Creating the Wrapper
+
+```javascript
+const wrapper = createTimeoutWrapper({
+  // Get remaining time from Lambda context (for Lambda/Netlify)
+  getRemainingTimeInMillis: context.getRemainingTimeInMillis,
+  // OR use fallback timer for local testing
+  // isUsingFallbackTimer: true,
+  // getRemainingTimeInMillis: () => 10000, // 10 seconds
+
+  // Set safety margin (how early to detect timeout)
+  safetyMarginMs: 3000, // 3 seconds
+
+  // Enable logging
+  logger: console.log
+});
+```
+
+#### 2. Using the Wrapper
+
+```javascript
+const result = await wrapper(
+  // Main function - your primary logic
+  async () => {
+    // Do your work here
+    return { success: true };
+  },
+
+  // Timeout handler - runs when timeout is imminent
+  async () => {
+    // Handle timeout gracefully
+    return { timedOut: true };
+  },
+
+  // User cleanup handler - always runs after success or timeout
+  async () => {
+    // Clean up resources here (database connections, etc.)
+  }
+);
+```
+
+#### 3. Error Handling
+
+```javascript
+try {
+  const result = await wrapper(/* ... */);
+  return result;
+} catch (error) {
+  // Check if it's a timeout error
+  if (error.isLambdaTimeout) {
+    // Handle timeout-specific error case
+  }
+
+  // Handle other errors
+}
+```
+
+### Implementation Details for Netlify Functions
+
+1. **Directory Structure:**
+   ```
+   your-project/
+   ├── netlify.toml
+   └── netlify/
+       └── functions/
+           └── your-function.js
+   ```
+
+2. **Required Dependencies:**
+   - For JavaScript:
+     ```bash
+     npm install @hopdrive/lambda-timeout-wrapper
+     ```
+   - For TypeScript:
+     ```bash
+     npm install @hopdrive/lambda-timeout-wrapper
+     npm install --save-dev typescript @netlify/functions @types/node
+     ```
+
+3. **Running Locally:**
+   ```bash
+   npm install -g netlify-cli
+   netlify dev
+   ```
+
+4. **Testing:**
+   Access your function at: `http://localhost:8888/.netlify/functions/your-function`
+
+### Testing Timeout Behavior
+
+To test timeout behavior:
+
+1. **Increase task duration:**
+   - Modify the setTimeout duration in the examples to exceed the timeout limit
+
+2. **Decrease safety margin:**
+   - Set a smaller safetyMarginMs value to test different cleanup timing
+
+3. **Observe graceful shutdown:**
+   - Watch how resources are properly cleaned up when timeout occurs
+
 ## License
 
 MIT

examples/local-fallback-example.js

@@ -0,0 +1,81 @@
+/**
+ * Local testing example using lambda-timeout-wrapper with fallback timer
+ *
+ * This example demonstrates how to use the wrapper outside of an AWS Lambda environment
+ * using the fallback timer mode for local development and testing.
+ */
+
+const { createTimeoutWrapper } = require('@hopdrive/lambda-timeout-wrapper');
+
+// This function demonstrates how to test the timeout wrapper locally
+async function runLocalTest() {
+  console.log('Starting local test with fallback timer');
+
+  // Create a wrapper with fallback timer mode
+  // (no Lambda context is needed)
+  const wrapper = createTimeoutWrapper({
+    // Enable fallback timer mode
+    isUsingFallbackTimer: true,
+
+    // Set a fixed time limit (10 seconds in this example)
+    getRemainingTimeInMillis: () => 10000,
+
+    // Set a 2 second safety margin
+    safetyMarginMs: 2000,
+
+    // Log messages
+    logger: console.log
+  });
+
+  try {
+    // Use the wrapper
+    const result = await wrapper(
+      // Main function - this will either complete or time out
+      async () => {
+        console.log('Main function started');
+
+        // Simulate a long-running task
+        console.log('Running task for 9 seconds...');
+        await new Promise(resolve => setTimeout(resolve, 9000));
+
+        // This will execute if we don't time out
+        console.log('Task completed');
+        return 'Success! Task completed within time limit';
+      },
+
+      // Timeout handler - runs when a timeout is detected
+      async () => {
+        console.log('Timeout detected!');
+        return 'Timeout occurred - handled gracefully';
+      },
+
+      // User cleanup handler - optional but should be included for proper usage
+      async () => {
+        console.log('Cleanup handler called - this always runs');
+        // Add cleanup logic here
+      }
+    );
+
+    console.log('Result:', result);
+    return result;
+  }
+  catch (error) {
+    console.error('Error during execution:', error);
+    throw error;
+  }
+}
+
+// Run the example if this file is executed directly
+if (require.main === module) {
+  runLocalTest()
+    .then(result => {
+      console.log('Test completed with result:', result);
+    })
+    .catch(error => {
+      console.error('Test failed with error:', error);
+      process.exit(1);
+    });
+}
+
+// Export for use in other modules
+module.exports = { runLocalTest };

examples/netlify-function-example.js

@@ -0,0 +1,124 @@
+/**
+ * Example Netlify function that demonstrates using lambda-timeout-wrapper
+ *
+ * This example shows how to:
+ * 1. Create a timeout wrapper with appropriate configuration
+ * 2. Implement a main function with long-running operations
+ * 3. Add timeout and cleanup handlers
+ * 4. Handle the response appropriately
+ */
+
+const { createTimeoutWrapper } = require('@hopdrive/lambda-timeout-wrapper');
+
+// Example of a database connection that would need cleanup
+let dbConnection = null;
+
+// Simulates connecting to a database
+const connectToDatabase = async () => {
+  console.log('Connecting to database...');
+  // Simulate connection delay
+  await new Promise(resolve => setTimeout(resolve, 1000));
+  dbConnection = {
+    isConnected: true,
+    close: async () => {
+      console.log('Database connection closed gracefully');
+      dbConnection = null;
+    }
+  };
+  console.log('Connected to database');
+  return dbConnection;
+};
+
+// Simulates a long-running database query
+const runLongQuery = async () => {
+  console.log('Running long database query...');
+  // Simulate a long-running operation
+  await new Promise(resolve => setTimeout(resolve, 5000));
+  console.log('Query completed');
+  return { results: ['item1', 'item2', 'item3'] };
+};
+
+// Main Netlify function handler
+exports.handler = async (event, context) => {
+  // Create timeout wrapper with Lambda context
+  const wrapper = createTimeoutWrapper({
+    // Get remaining time from Lambda context
+    getRemainingTimeInMillis: () => context.getRemainingTimeInMillis(),
+    // Set a 3-second safety margin (default is 5000ms)
+    safetyMarginMs: 3000,
+    // Log messages for debugging
+    logger: console.log
+  });
+
+  try {
+    // Use the wrapper around your function execution
+    const result = await wrapper(
+      // Main function - this is where your primary logic goes
+      async () => {
+        // Connect to the database
+        await connectToDatabase();
+
+        // Run a long query that might timeout
+        const queryResults = await runLongQuery();
+
+        // Process results
+        return {
+          statusCode: 200,
+          body: JSON.stringify({
+            message: 'Operation completed successfully',
+            data: queryResults
+          })
+        };
+      },
+
+      // Timeout handler - runs when timeout is imminent
+      async () => {
+        console.log('TIMEOUT IMMINENT: Beginning graceful shutdown...');
+        // Add any critical cleanup operations here
+
+        // Return a timeout response to the client
+        return {
+          statusCode: 408,
+          body: JSON.stringify({
+            message: 'Request timeout',
+            error: 'The operation took too long to complete'
+          })
+        };
+      },
+
+      // User cleanup handler - always runs after either success or timeout
+      async () => {
+        // Close database connection if it exists
+        if (dbConnection && dbConnection.isConnected) {
+          await dbConnection.close();
+        }
+      }
+    );
+
+    // Return the result from the main function
+    return result;
+  }
+  catch (error) {
+    console.error('Error in Lambda function:', error);
+
+    // Check if it's a timeout error
+    if (error.isLambdaTimeout) {
+      return {
+        statusCode: 408,
+        body: JSON.stringify({
+          message: 'Request timeout',
+          error: 'The operation took too long to complete'
+        })
+      };
+    }
+
+    // Handle other errors
+    return {
+      statusCode: 500,
+      body: JSON.stringify({
+        message: 'Internal server error',
+        error: error.message
+      })
+    };
+  }
+};