(sendSmsEffect);\n```\n\n---\n\n## ๐ฅ **Core Features**\n\n### **๐ญ Dependency Injection Made Simple**\n\nAccess everything you need through clean `this` context:\n\n```javascript\nasync function myHandler(event) {\n const { \n env, // Environment variables\n providers, // Your business logic\n request, // HTTP headers & data\n cookies // Request cookies\n } = this;\n \n // Your logic here...\n}\n```\n\n### **๐ฆ Result Pattern (No More Try-Catch Hell)**\n\n```javascript\n// In your providers\nconst fetchUser = async function (userId) {\n const { client, env } = this;\n \n try {\n const user = await client.api.accounts(env.ACCOUNT_SID)\n .calls\n .list({ limit: 1 });\n \n return Result.ok(user[0]);\n } catch (error) {\n return Result.failed('User not found');\n }\n};\n\n// In your handlers\nconst userResult = await this.providers.fetchUser(event.userId);\n\nif (userResult.isError) {\n return new NotFoundError(userResult.error);\n}\n\nreturn new Response(userResult.data);\n```\n\n### **๐ฏ Smart Response Handling**\n\n```javascript\n// JSON Responses\nreturn new Response({ success: true, data: results }, 201);\n\n// TwiML Responses\nconst twiml = new Twilio.twiml.VoiceResponse();\ntwiml.say('Hello from RxJS-powered Twilio!');\nreturn new TwiMLResponse(twiml.toString());\n\n// Error Responses\nreturn new BadRequestError('Invalid input');\nreturn new NotFoundError('Resource not found');\nreturn new UnauthorizedError('Access denied');\nreturn new InternalServerError('Something went wrong');\n```\n\n---\n\n## ๐ **RxJS Effects API**\n\nFor advanced use cases, leverage the full power of reactive programming:\n\n### **Composition with Operators**\n\n```javascript\nconst complexWorkflow = context$ =>\n context$.pipe(\n // Validation\n requireFields('customerId', 'action'),\n authenticated(ctx => ctx.event.token),\n \n // Data fetching\n switchMap(ctx => \n ctx.providers.customerService.getProfile(ctx.event.customerId)\n ),\n \n // Business logic\n map(customer => ({\n id: customer.id,\n name: customer.name,\n tier: customer.subscriptions.length > 0 ? 'premium' : 'basic'\n })),\n \n // Response formatting\n apiResponse({ message: 'Profile retrieved successfully' }),\n \n // Error handling\n handleError(error => {\n if (error.code === 'CUSTOMER_NOT_FOUND') {\n return new NotFoundError('Customer not found');\n }\n return null; // Use default error handling\n })\n );\n```\n\n### **Built-in Operators**\n\n```javascript\n// Validation\nrequireFields('email', 'phone')\nvalidateEvent(event => event.email.includes('@'))\nauthenticated(ctx => checkApiKey(ctx.event.apiKey))\n\n// Data injection\ninjectEvent() // Get event data\ninjectEnv() // Get environment vars\ninjectClient() // Get Twilio client\ninjectProviders() // Get all providers\ninjectProvider('userService') // Get specific provider\n\n// Response formatting\nok() // 200 response\ncreated() // 201 response \napiResponse({ meta: { version: '1.0' } })\ntoTwiMLResponse() // Convert TwiML to response\n\n// Error handling\nhandleError() // Comprehensive error handling\nretryWithBackoff(3) // Retry failed operations\ntimeoutWithError(5000) // Timeout after 5 seconds\nfallback(defaultValue) // Provide fallback value\n```\n\n---\n\n## ๐งช **Testing Made Easy**\n\n### **Simple Testing (Original API)**\n\n```javascript\nrequire('twilio-functions-utils/dist/lib/twilio.mock.js');\n\nconst { useMock, Response } = require('twilio-functions-utils');\nconst { myHandler } = require('../functions/myHandler');\n\nconst mockFn = useMock(myHandler, {\n providers: {\n sendSms: async (to, message) => ({ sid: 'SM123', status: 'sent' })\n },\n env: { ACCOUNT_SID: 'AC123' },\n client: { /* mock Twilio client */ }\n});\n\ntest('should send SMS successfully', async () => {\n const result = await mockFn({ to: '+1234567890', message: 'Hello!' });\n \n expect(result).toBeInstanceOf(Response);\n expect(result.statusCode).toBe(201);\n});\n```\n\n### **Advanced Testing (RxJS Effects)**\n\n```javascript\nconst { testEffect, marbleTest, expectEmissions } = require('twilio-functions-utils');\n\ntest('should handle SMS sending with marble testing', () => {\n marbleTest(({ cold, expectObservable }) => {\n const context$ = cold('a|', {\n a: { event: { to: '+1234567890', message: 'Test' } }\n });\n\n const result$ = sendSmsEffect(context$);\n\n expectObservable(result$).toBe('a|', {\n a: expect.objectContaining({ statusCode: 200 })\n });\n });\n});\n```\n\n---\n\n## ๐ **Flex Integration**\n\nBuilt-in support for Twilio Flex token validation:\n\n```javascript\n// Simple API\nexports.handler = useInjection(myHandler, {\n providers: { taskService },\n validateToken: true // Automatically validates Flex tokens\n});\n\n// RxJS API \nconst flexEffect = context$ =>\n context$.pipe(\n validateFlexToken(), // Validates token from event.Token\n // ... rest of your logic\n );\n\n// Custom token validation\nconst customFlexEffect = context$ =>\n context$.pipe(\n validateFlexTokenWithOptions({\n tokenField: 'customToken',\n onValidation: (result) => console.log('Token validated:', result)\n }),\n // ... rest of your logic\n );\n```\n\n---\n\n## ๐ **Migration Guide**\n\n### **From v2.4.x to v2.5.0: Zero Breaking Changes! ๐**\n\nYour existing code works without any modifications:\n\n```javascript\n// This code works exactly the same in v2.5.0\nconst { useInjection, Response, Result } = require('twilio-functions-utils');\n\nasync function existingHandler(event) {\n const result = await this.providers.existingProvider(event);\n return new Response(result.data);\n}\n\nexports.handler = useInjection(existingHandler, {\n providers: { existingProvider }\n});\n```\n\n### **What's New in v2.5.0:**\n- โ
**RxJS-Powered Architecture** - Enhanced reactive stream processing under the hood\n- โ
**Advanced Effects API** - Optional RxJS Effects for complex workflows\n- โ
**Enhanced Testing** - Marble testing and improved mocking capabilities\n- โ
**Better Performance** - Optimized stream processing and error handling\n- โ
**Full TypeScript Support** - Complete type safety with proper inference\n\n---\n\n## ๐ **API Reference**\n\n### **Core Functions**\n\n| Function | Description |\n|----------|-------------|\n| `useInjection(fn, options)` | Main dependency injection wrapper |\n| `twilioEffect(effect, options)` | RxJS Effects wrapper |\n| `useMock(fn, options)` | Testing utility (test environment only) |\n\n### **Response Classes**\n\n| Class | Status Code | Usage |\n|-------|-------------|-------|\n| `Response(body, statusCode)` | Custom | General responses |\n| `TwiMLResponse(twiml)` | 200 | TwiML responses |\n| `BadRequestError(message)` | 400 | Invalid input |\n| `UnauthorizedError(message)` | 401 | Authentication required |\n| `NotFoundError(message)` | 404 | Resource not found |\n| `InternalServerError(message)` | 500 | Server errors |\n\n### **Utility Classes**\n\n| Class | Description |\n|-------|-------------|\n| `Result.ok(data)` | Success result wrapper |\n| `Result.failed(error)` | Error result wrapper |\n| `typeOf(value)` | Enhanced type checking |\n\n---\n\n## ๐ง **Troubleshooting**\n\n### **Common Issues**\n\n#### **\"Module not found\" Error**\n```bash\n# Ensure you've installed the package\nnpm install twilio-functions-utils\n\n# For TypeScript projects, ensure proper types\nnpm install --save-dev typescript @types/node\n```\n\n#### **Testing Issues**\n```javascript\n// โ Wrong - Missing mock import\nconst { useMock } = require('twilio-functions-utils');\n\n// โ
Correct - Import mock first\nrequire('twilio-functions-utils/dist/lib/twilio.mock.js');\nconst { useMock } = require('twilio-functions-utils');\n\n// Ensure NODE_ENV=test\nprocess.env.NODE_ENV = 'test';\n```\n\n#### **RxJS Operator Issues**\n```bash\n# Ensure RxJS is installed\nnpm install rxjs@^7.8.2\n\n# Import operators correctly\nconst { switchMap, map } = require('rxjs/operators');\n```\n\n#### **TypeScript Compilation Errors**\n```json\n// tsconfig.json - Ensure proper configuration\n{\n \"compilerOptions\": {\n \"target\": \"ES2018\",\n \"module\": \"commonjs\",\n \"strict\": true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": true\n }\n}\n```\n\n#### **Runtime Context Issues**\n```javascript\n// โ Wrong - Arrow functions lose 'this' context\nconst handler = (event) => {\n // 'this' is undefined here\n};\n\n// โ
Correct - Use regular functions\nasync function handler(event) {\n // 'this' context available here\n const { env, providers } = this;\n}\n```\n\n### **Performance Tips**\n\n- Use `injectMany()` instead of multiple `inject()` calls\n- Leverage RxJS operators for complex data transformations\n- Use `Result` pattern to avoid try-catch overhead\n- Enable TypeScript strict mode for better optimization\n\n### **Getting Help**\n\n- ๐ Check [documentation](https://iagocalazans.github.io/twilio-functions-utils)\n- ๐ Report bugs on [GitHub Issues](https://github.com/iagocalazans/twilio-functions-utils/issues)\n- ๐ฌ Ask questions in [Twilio Community](https://www.twilio.com/community)\n\n---\n\n## ๐ค **Contributing**\n\nWe welcome contributions! Here's how you can help:\n\n1. **๐ Report bugs** - Open an issue with reproduction steps\n2. **๐ก Suggest features** - Describe your use case and proposed solution \n3. **๐ Improve docs** - Help make our documentation clearer\n4. **๐งช Write tests** - Add test cases for new features\n5. **๐ง Submit PRs** - Follow our coding standards and include tests\n\n---\n\n## ๐ **Community & Support**\n\n### **๐ Resources**\n- ๐ **[Project Homepage](https://iagocalazans.github.io/twilio-functions-utils)** - Documentation and guides\n- ๐ฆ **[NPM Package](https://www.npmjs.com/package/twilio-functions-utils)** - Package details and versions\n- ๐ **[GitHub Repository](https://github.com/iagocalazans/twilio-functions-utils)** - Source code and issues\n\n### **๐ Getting Help**\n- ๐ **[Report Issues](https://github.com/iagocalazans/twilio-functions-utils/issues)** - Bug reports and feature requests\n- ๐ฌ **[Twilio Community](https://www.twilio.com/community)** - General Twilio development discussions\n- ๐ง **[Contact Author](mailto:iago.calazans@gmail.com)** - Direct support for complex issues\n\n### **๐ค Contributing**\n- ๐ **[Pull Requests](https://github.com/iagocalazans/twilio-functions-utils/pulls)** - Code contributions welcome\n- ๐ **[Contributing Guide](https://github.com/iagocalazans/twilio-functions-utils/blob/master/CONTRIBUTING.md)** - How to contribute\n- ๐งช **[Running Tests](https://github.com/iagocalazans/twilio-functions-utils#testing)** - Test your changes\n\n---\n\n## ๐ **License**\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n## ๐จโ๐ป **Author**\n\n**[Iago Calazans](https://github.com/iagocalazans)** - Senior Node.js Engineer\n\n---\n\n\n\n**โญ If this library helps you build amazing Twilio Functions, give it a star! โญ**\n\nMade with โค๏ธ and โ for the Twilio community\n\n
","readmeFilename":"README.md","users":{"iagocalazans":true}}![](\"https://avatars.githubusercontent.com/u/109142?s=200&v=4\")
\n\n   \n\n## ๐ **Next-Generation Twilio Functions Development**\n\nA powerful, **RxJS-powered** utility library that revolutionizes Twilio serverless function development with reactive streams, functional composition, and zero-boilerplate dependency injection.\n\n**โจ What's New in v2.4+:**\n- ๐ **Reactive Streams**: Built on RxJS for composable, testable functions\n- ๐ฏ **Zero Breaking Changes**: 100% backward compatible with existing code\n- ๐งช **Enhanced Testing**: Marble testing and advanced mocking capabilities\n- ๐ **Two API Levels**: Simple injection API + powerful Effects API\n- โก **Better Performance**: Optimized stream processing\n- ๐ **Type Safe**: Full TypeScript support with proper inference\n\n```bash\nnpm install twilio-functions-utils\n```\n\n## ๐ **Requirements & Compatibility**\n\n- **Node.js**: >= 14.0.0\n- **Twilio Runtime**: Compatible with Twilio Functions runtime\n- **TypeScript**: >= 5.0.0 (for TypeScript projects)\n- **Dependencies**: RxJS 7.8.2+, Twilio SDK 3.77.2+\n\n### **Peer Dependencies**\n- `twilio` - Twilio JavaScript SDK\n- `@twilio/runtime-handler` - For local development\n\n---\n\n## ๐ **Development Setup**\n\n### **Building the Project**\n```bash\nnpm run build # Compile TypeScript to JavaScript\nnpm run prebuild # Clean build directory before building\n```\n\n### **Testing**\n```bash\nnpm run test # Run Jest test suite with coverage\nNODE_ENV=test npm test # Ensure test environment\n```\n\n### **Documentation**\n```bash\nnpm run docs # Generate JSDoc documentation\n```\n\n### **Project Structure**\nThe library supports flexible directory structures:\n- `./functions/` or `./src/functions/` for your Twilio Functions\n- `./assets/` or `./src/assets/` for static assets\n- Automatically detected during testing\n\n---\n\n## ๐ฏ **Quick Start**\n\n### **Option 1: Simple API (Familiar & Easy)**\n\n```javascript\nconst { useInjection, Response, BadRequestError, Result } = require('twilio-functions-utils');\n\n// Provider: Your business logic\nconst sendSmsProvider = async function (to, message) {\n const { client } = this;\n \n try {\n const result = await client.messages.create({\n to,\n from: '+1234567890',\n body: message\n });\n return Result.ok({ sid: result.sid, status: 'sent' });\n } catch (error) {\n return Result.failed(error.message);\n }\n};\n\n// Handler: Your Twilio Function\nasync function sendSmsHandler(event) {\n const { env, providers } = this;\n const { to, message } = event;\n \n if (!to || !message) {\n return new BadRequestError('Missing \"to\" or \"message\" parameters');\n }\n \n const result = await providers.sendSms(to, message);\n \n if (result.isError) {\n return new BadRequestError(result.error);\n }\n \n return new Response(result.data, 201);\n}\n\n// Export for Twilio\nexports.handler = useInjection(sendSmsHandler, {\n providers: { sendSms: sendSmsProvider }\n});\n```\n\n### **Option 2: RxJS Effects API (Advanced & Powerful)**\n\n```javascript\nconst { \n twilioEffect, \n injectEvent, \n injectClient, \n requireFields, \n ok, \n handleError \n} = require('twilio-functions-utils');\n\nconst { switchMap, map } = require('rxjs/operators');\n\nconst sendSmsEffect = context$ => \n context$.pipe(\n requireFields('to', 'message'),\n injectEvent(),\n injectClient(),\n switchMap(([event, client]) =>\n client.messages.create({\n to: event.to,\n from: '+1234567890',\n body: event.message\n })\n ),\n map(result => ({ sid: result.sid, status: 'sent' })),\n ok(),\n handleError()\n );\n\nexports.handler = twilioEffect(sendSmsEffect);\n```\n\n### **TypeScript Examples**\n\n```typescript\nimport { \n useInjection, \n Response, \n BadRequestError, \n Result,\n InjectorFunction,\n ProviderFunction \n} from 'twilio-functions-utils';\n\n// Type your environment variables\ninterface MyEnv {\n ACCOUNT_SID: string;\n AUTH_TOKEN: string;\n FROM_NUMBER: string;\n}\n\n// Type your event data\ninterface SmsEvent {\n to: string;\n message: string;\n}\n\n// Type your providers\ninterface MyProviders {\n sendSms: (to: string, message: string) => Promise