{"_id":"@benpley/wappler-csvstreamer","name":"@benpley/wappler-csvstreamer","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@benpley/wappler-csvstreamer","version":"1.0.0","description":"Wappler extension for streaming CSV files to browser with download support","license":"MIT","author":{"name":"Ben Pleysier"},"keywords":["wappler","wappler-extension","csv","csv-export","csv-download","server-connect","data-export","file-streaming"],"peerDependencies":{},"wappler":{"type":"extension","category":"server-connect","serverModel":["node"]},"main":"index.js","scripts":{"test":"npm link"},"_id":"@benpley/wappler-csvstreamer@1.0.0","_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-xPhTCKTWccohpnjmhI9pbYTmcJajDQidwwqKLd54/ahzdNz5AIJW1JkRY5GkjQqPxR/vOox4ZSLrattsX5De6w==","shasum":"e026a0f49262aa8c50bbba3c0323060a21a54e87","tarball":"https://registry.npmjs.org/@benpley/wappler-csvstreamer/-/wappler-csvstreamer-1.0.0.tgz","fileCount":6,"unpackedSize":16557,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGgM1PexGH28MLW3jzE23VuiJKCu1yIF22lhy1N2pXsXAiEA2jCVhyRoutraRgUt9FV1MHK6uv/SNgw+MkJXdylUXdg="}]},"_npmUser":{"name":"benpley","email":"ben@pleysier.com.au"},"directories":{},"maintainers":[{"name":"benpley","email":"ben@pleysier.com.au"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/wappler-csvstreamer_1.0.0_1764291874413_0.3477998860425775"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-28T01:04:34.332Z","1.0.0":"2025-11-28T01:04:34.612Z","modified":"2025-11-28T01:04:34.883Z"},"maintainers":[{"name":"benpley","email":"ben@pleysier.com.au"}],"description":"Wappler extension for streaming CSV files to browser with download support","keywords":["wappler","wappler-extension","csv","csv-export","csv-download","server-connect","data-export","file-streaming"],"author":{"name":"Ben Pleysier"},"license":"MIT","readme":"# Wappler CSV Streamer Extension\n\nStream CSV files directly to the browser for download or display in your Wappler applications.\n\n## Features\n\n- ✅ Stream CSV files for download\n- ✅ Optional inline display mode\n- ✅ Automatic content-type and caching headers\n- ✅ Browser caching support with ETag\n- ✅ 304 Not Modified responses for optimal performance\n- ✅ Custom display filenames\n- ✅ UTF-8 encoding support\n- ✅ Comprehensive error handling\n- ✅ Supports both absolute and relative paths\n\n## Installation\n\n### 1. Install as per Wappler Extension Guidelines\n\nhttps://community.wappler.io/t/how-to-install-custom-wappler-extensions/49982\n\n### 2. Restart Wappler\n\nAfter installation, you **must restart Wappler** for it to recognize the new extension.\n\n1. Save all your work\n2. Close Wappler completely\n3. Reopen Wappler\n4. Open your project\n\n### 3. Verify Installation\n\nAfter restart, the extension should appear in Server Connect:\n\n1. Open any Server Connect file\n2. Click the \"+\" button to add a step\n3. Look for \"CSV Operations\" group\n4. You should see \"Stream CSV\" action\n\n## Quick Start\n\n### Basic Usage - Download CSV\n\nIn your Server Connect action:\n\n```json\n{\n  \"name\": \"streamCSV\",\n  \"module\": \"csvstreamer\",\n  \"action\": \"stream\",\n  \"options\": {\n    \"filepath\": \"exports/data.csv\",\n    \"disposition\": \"attachment\"\n  }\n}\n```\n\n### Custom Filename\n\n```json\n{\n  \"name\": \"downloadCSV\",\n  \"module\": \"csvstreamer\",\n  \"action\": \"stream\",\n  \"options\": {\n    \"filepath\": \"exports/data.csv\",\n    \"filename\": \"Customer Report 2025.csv\",\n    \"disposition\": \"attachment\"\n  }\n}\n```\n\n### Display in Browser (Inline)\n\n```json\n{\n  \"name\": \"viewCSV\",\n  \"module\": \"csvstreamer\",\n  \"action\": \"stream\",\n  \"options\": {\n    \"filepath\": \"exports/data.csv\",\n    \"disposition\": \"inline\"\n  }\n}\n```\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `filepath` | String | Yes | - | Path to the CSV file (relative to project root) |\n| `filename` | String | No | Original filename | Display name for the CSV |\n| `disposition` | String | No | `attachment` | `attachment` (download) or `inline` (display) |\n| `cache` | Boolean | No | `true` | Enable browser caching with ETag |\n\n## Frontend Usage\n\n### Download Link\n\n```html\n<!-- Direct download link -->\n<a href=\"/api/[server-action]/export.csv\" class=\"btn btn-primary\">\n  Download CSV\n</a>\n\n<!-- With dynamic filename -->\n<a href=\"/api/export-data\" download=\"report.csv\" class=\"btn btn-success\">\n  Export Report\n</a>\n```\n\n### Programmatic Download\n\n```html\n<button dmx-on:click=\"downloadCSV.load()\">Export Data</button>\n\n<!-- Server Connect component -->\n<dmx-serverconnect \n  id=\"downloadCSV\" \n  url=\"/api/export-data\">\n</dmx-serverconnect>\n```\n\n## Response Headers\n\nThe extension automatically sets optimized headers:\n\n```\nContent-Type: text/csv; charset=utf-8\nContent-Length: [file size]\nContent-Disposition: attachment; filename=\"export.csv\"\nCache-Control: public, max-age=3600\nETag: \"[timestamp]-[size]\"\n```\n\n## Caching Behavior\n\nWhen caching is enabled (default):\n\n1. **First request**: Returns full CSV with ETag header\n2. **Subsequent requests**: Browser sends `If-None-Match` header\n3. **If unchanged**: Returns `304 Not Modified` (no data transfer)\n4. **If changed**: Returns new CSV with updated ETag\n\nCache duration: **1 hour** (3600 seconds)\n\n## Common Use Cases\n\n### Export Database Query Results\n\n```json\n{\n  \"exec\": {\n    \"steps\": [\n      {\n        \"name\": \"query_data\",\n        \"module\": \"dbconnector\",\n        \"action\": \"select\",\n        \"options\": {\n          \"connection\": \"db\",\n          \"sql\": {\n            \"query\": \"SELECT * FROM customers\"\n          }\n        }\n      },\n      {\n        \"name\": \"create_csv\",\n        \"module\": \"csvwriter\",\n        \"action\": \"write\",\n        \"options\": {\n          \"data\": \"{{query_data}}\",\n          \"filepath\": \"exports/customers.csv\"\n        }\n      },\n      {\n        \"name\": \"stream_csv\",\n        \"module\": \"csvstreamer\",\n        \"action\": \"stream\",\n        \"options\": {\n          \"filepath\": \"exports/customers.csv\",\n          \"filename\": \"Customers Export.csv\"\n        }\n      }\n    ]\n  }\n}\n```\n\n### Secure Download with Authentication\n\n```json\n{\n  \"exec\": {\n    \"steps\": [\n      {\n        \"name\": \"restrict\",\n        \"module\": \"auth\",\n        \"action\": \"restrict\",\n        \"options\": {\n          \"provider\": \"security\"\n        }\n      },\n      {\n        \"name\": \"verify_access\",\n        \"module\": \"dbconnector\",\n        \"action\": \"single\",\n        \"options\": {\n          \"connection\": \"db\",\n          \"sql\": {\n            \"query\": \"SELECT filepath FROM exports WHERE id = ? AND user_id = ?\",\n            \"params\": [\"{{$_PARAM.id}}\", \"{{identity.id}}\"]\n          }\n        }\n      },\n      {\n        \"name\": \"stream_csv\",\n        \"module\": \"csvstreamer\",\n        \"action\": \"stream\",\n        \"options\": {\n          \"filepath\": \"{{verify_access.filepath}}\",\n          \"filename\": \"My Export.csv\"\n        }\n      }\n    ]\n  }\n}\n```\n\n### Dynamic Filename with Date\n\n```json\n{\n  \"name\": \"stream_csv\",\n  \"module\": \"csvstreamer\",\n  \"action\": \"stream\",\n  \"options\": {\n    \"filepath\": \"exports/daily-report.csv\",\n    \"filename\": \"{{NOW.formatDate('yyyy-MM-dd')}}-report.csv\"\n  }\n}\n```\n\n## Path Resolution\n\nThe extension supports multiple path types:\n\n1. **Relative to project root**:\n   ```\n   \"filepath\": \"exports/data.csv\"\n   // Resolves to: /your-project/exports/data.csv\n   ```\n\n2. **Absolute paths**:\n   ```\n   \"filepath\": \"/var/data/exports/data.csv\"\n   // Uses the path as-is\n   ```\n\n## Error Handling\n\nClear error messages for common issues:\n\n- **File not found**: `\"CSV file not found: [path]\"`\n- **Missing filepath**: `\"File path is required\"`\n- **Read error**: `\"Error reading CSV file: [error]\"`\n\n## Troubleshooting\n\n### Extension Not Showing in Wappler\n\n**Solution:** \n1. Verify the package was installed: check `node_modules/@benpley/wappler-csvstreamer`\n2. Make sure Wappler is completely closed and restarted\n3. Clear Wappler cache if needed\n\n### \"Module not found\" Error\n\n**Solution:**\n- Verify installation: `npm list @benpley/wappler-csvstreamer`\n- Reinstall if needed: `npm install @benpley/wappler-csvstreamer`\n- Restart Wappler completely\n\n### CSV Not Downloading\n\n**Solution:**\n1. Check the `disposition` parameter is set to `\"attachment\"`\n2. Verify file exists at specified path\n3. Check response headers in browser DevTools\n\n### Character Encoding Issues\n\n**Solution:**\n- The extension uses UTF-8 encoding by default\n- Ensure your CSV files are saved with UTF-8 encoding\n- Special characters should display correctly in most modern applications\n\n## Performance Tips\n\n1. ✅ Enable caching for static CSV files\n2. ✅ Use relative paths when possible\n3. ✅ Add authentication early in the workflow\n4. ✅ Consider generating CSVs on-demand rather than pre-generating\n5. ✅ Use compression for large CSV files\n\n## Advantages Over fs.download\n\n| Feature | fs.download | csvstreamer |\n|---------|-------------|-------------|\n| Download support | ✅ | ✅ |\n| Automatic headers | ❌ | ✅ |\n| UTF-8 encoding | ❌ | ✅ |\n| Caching support | ❌ | ✅ |\n| ETag support | ❌ | ✅ |\n| 304 responses | ❌ | ✅ |\n| Enhanced errors | ❌ | ✅ |\n\n## Requirements\n\n- **Node.js**: >= 12.0.0\n- **Wappler**: 5.x or higher\n\n## License\n\nMIT License - see [LICENSE.md](./LICENSE.md) for details\n\n## Author\n\nBen Pleysier\n\n## Support\n\nFor issues or questions:\n- Check the troubleshooting section above\n- Visit the [Wappler Community Forum](https://community.wappler.io)\n\n## Related Extensions\n\n- [@benpley/wappler-pdfstreamer](https://www.npmjs.com/package/@benpley/wappler-pdfstreamer) - Stream PDF files\n","readmeFilename":"README.md","_rev":"1-15e6c9bd3ae70430ab8487415969d12d"}