node-red-contrib-couchdb-nodes 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kanr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,311 @@
+# node-red-contrib-couchdb-nodes
+
+Node-RED nodes for performing CRUD operations on Apache CouchDB databases.
+
+[![npm version](https://badge.fury.io/js/node-red-contrib-couchdb-nodes.svg)](https://www.npmjs.com/package/node-red-contrib-couchdb-nodes)
+[![Node.js CI](https://github.com/kanr/node-red-contrib-couchdb-nodes/workflows/Test/badge.svg)](https://github.com/kanr/node-red-contrib-couchdb-nodes/actions)
+
+## Features
+
+- **Server Configuration**: Centralized CouchDB connection management with authentication
+- **Document Operations**: Query, insert, get, and update documents
+- **Database Management**: Create, delete, and list databases
+- **View Queries**: Execute CouchDB views with filtering and pagination
+- **Optimistic Concurrency**: Built-in revision control for safe updates
+- **Error Handling**: Dual-output pattern for success/error flow separation
+- **Pagination**: Support for limit/skip in queries and document listing
+
+## Installation
+
+Install via Node-RED's palette manager or run:
+
+```bash
+npm install node-red-contrib-couchdb-nodes
+```
+
+## Requirements
+
+- **Node.js**: 10.0.0 or higher
+- **Node-RED**: 1.0.0 or higher
+- **CouchDB**: 2.0 or higher
+
+## Available Nodes
+
+### CouchDB Server (Configuration)
+
+Configuration node that stores CouchDB connection details. Used by all operational nodes.
+
+**Properties:**
+- `hostname`: CouchDB server hostname (default: localhost)
+- `port`: CouchDB port (default: 5984)
+- `username`: Optional authentication username
+- `password`: Optional authentication password (stored securely)
+
+### CouchDB Query
+
+Execute CouchDB view queries with filtering and pagination options.
+
+**Inputs:**
+- `msg.database` (optional): Override configured database
+- `msg.view` (optional): Override configured view
+- `msg.key` (optional): Filter by specific key
+- `msg.limit` (optional): Maximum documents to return
+- `msg.skip` (optional): Number of documents to skip
+- `msg.include_docs` (optional): Include full documents in results
+
+**Outputs:**
+- **Output 1 (Success)**: `msg.payload` contains query results
+- **Output 2 (Error)**: Error information
+
+**Example:**
+```javascript
+msg.database = "products";
+msg.view = "catalog/by_category";
+msg.key = "electronics";
+msg.limit = 10;
+return msg;
+```
+
+### CouchDB Insert
+
+Insert new documents into CouchDB.
+
+**Inputs:**
+- `msg.payload`: Object to insert (must be a valid object, not string/array/null)
+- `msg.database` (optional): Override configured database
+
+**Outputs:**
+- **Output 1 (Success)**: `msg.payload` contains inserted document with `_id` and `_rev`
+- **Output 2 (Error)**: Error information
+
+**Example:**
+```javascript
+msg.payload = {
+  type: "product",
+  name: "Laptop",
+  price: 999.99
+};
+return msg;
+```
+
+### CouchDB Get
+
+Retrieve a specific document by ID.
+
+**Inputs:**
+- `msg.docId`: Document ID to retrieve
+- `msg.database` (optional): Override configured database
+
+**Outputs:**
+- **Output 1 (Success)**: `msg.payload` contains the document
+- **Output 2 (Error)**: Error information (e.g., 404 if not found)
+
+**Example:**
+```javascript
+msg.docId = "product-12345";
+return msg;
+```
+
+### CouchDB Update
+
+Update existing documents with optimistic concurrency control.
+
+**Inputs:**
+- `msg.payload`: Document object with `_id` and `_rev` fields
+- `msg.database` (optional): Override configured database
+
+**Important:** The document must include both `_id` and `_rev`. Use the Get node first to retrieve the current version.
+
+**Outputs:**
+- **Output 1 (Success)**: `msg.payload` contains updated document info with new `_rev`
+- **Output 2 (Error)**: Error information (e.g., 409 conflict if document was modified)
+
+**Example:**
+```javascript
+// First, get the document
+// Then update it:
+msg.payload._rev = "2-abc123";  // Current revision from Get node
+msg.payload.price = 899.99;      // Update field
+return msg;
+```
+
+### CouchDB Create DB
+
+Create a new CouchDB database.
+
+**Inputs:**
+- `msg.database`: Name of database to create
+
+**Outputs:**
+- **Output 1 (Success)**: Confirmation message
+- **Output 2 (Error)**: Error information
+
+### CouchDB Delete DB
+
+Delete a CouchDB database.
+
+**Inputs:**
+- `msg.database`: Name of database to delete
+
+**Outputs:**
+- **Output 1 (Success)**: Confirmation message
+- **Output 2 (Error)**: Error information
+
+### CouchDB List DBs
+
+List all databases on the CouchDB server.
+
+**Outputs:**
+- **Output 1 (Success)**: `msg.payload` contains array of database names
+- **Output 2 (Error)**: Error information
+
+### CouchDB List Docs
+
+List documents in a database with pagination support.
+
+**Inputs:**
+- `msg.database` (optional): Override configured database
+- `msg.limit` (optional): Maximum documents to return
+- `msg.skip` (optional): Number of documents to skip
+- `msg.include_docs` (optional): Include full document content
+
+**Outputs:**
+- **Output 1 (Success)**: `msg.payload` contains document list
+- **Output 2 (Error)**: Error information
+
+## Usage Patterns
+
+### Basic Query Flow
+
+```
+[Inject] → [CouchDB Query] → [Debug]
+                           → [Error Handler]
+```
+
+### Insert with Error Handling
+
+```
+[Function] → [CouchDB Insert] → [Success Handler]
+                              → [Error Logger]
+```
+
+### Update with Get-Modify-Update Pattern
+
+```
+[Inject] → [CouchDB Get] → [Function: Modify] → [CouchDB Update] → [Debug]
+                        → [Error Handler]                        → [Error Handler]
+```
+
+### Pagination Example
+
+```javascript
+// In a Function node before CouchDB Query
+var pageSize = 20;
+var pageNumber = msg.page || 0;
+
+msg.limit = pageSize;
+msg.skip = pageNumber * pageSize;
+msg.include_docs = true;
+
+return msg;
+```
+
+## Error Handling
+
+All operational nodes use a dual-output pattern:
+
+- **First output**: Successful operations
+- **Second output**: Errors (with detailed error information)
+
+This allows you to route errors to dedicated error handling flows without cluttering your success path.
+
+**Example error message:**
+```javascript
+{
+  error: {
+    message: "Document update conflict",
+    status: 409,
+    reason: "Document update conflict"
+  }
+}
+```
+
+## CouchDB Concepts
+
+### Document Revisions
+
+CouchDB uses `_rev` fields for optimistic concurrency control. Every document has a revision that changes with each update. When updating a document, you must provide the current `_rev` to prevent conflicts.
+
+**Workflow:**
+1. **Get** the document (retrieves current `_rev`)
+2. **Modify** the document fields
+3. **Update** with the current `_rev`
+
+If another process updates the document between steps 1 and 3, you'll receive a 409 conflict error.
+
+### Views
+
+CouchDB views are stored queries defined in design documents. Views are referenced as `design_doc_name/view_name`.
+
+**Example:** `catalog/by_category` refers to the `by_category` view in the `catalog` design document.
+
+## Development
+
+### Running Tests
+
+```bash
+npm test
+```
+
+The test suite includes 37+ tests covering all node types and error conditions.
+
+### Project Structure
+
+```
+src/nodes/
+├── server/          Configuration node
+├── query/           View queries
+├── insert/          Document insertion
+├── get/             Document retrieval
+├── update/          Document updates
+├── create-db/       Database creation
+├── delete-db/       Database deletion
+├── list-dbs/        List databases
+└── list-docs/       List documents
+
+test/nodes/          Test suite
+```
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass (`npm test`)
+5. Submit a pull request
+
+## License
+
+MIT © kanr
+
+## Links
+
+- [GitHub Repository](https://github.com/kanr/node-red-contrib-couchdb-nodes)
+- [npm Package](https://www.npmjs.com/package/node-red-contrib-couchdb-nodes)
+- [Issue Tracker](https://github.com/kanr/node-red-contrib-couchdb-nodes/issues)
+- [Apache CouchDB](https://couchdb.apache.org/)
+- [Node-RED](https://nodered.org/)
+
+## Changelog
+
+### 1.0.0 (2026-02-21)
+
+- Initial release
+- CouchDB server configuration node
+- Document operations: query, insert, get, update
+- Database management: create, delete, list
+- Document listing with pagination
+- Comprehensive test coverage
+- GitHub Actions CI/CD

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "node-red-contrib-couchdb-nodes",
+  "version": "0.0.1",
+  "description": "Node-RED nodes for CouchDB CRUD operations",
+  "main": "src/nodes/index.js",
+  "scripts": {
+    "test": "mocha test/**/*.test.js --timeout 10000 --recursive"
+  },
+  "keywords": [
+    "node-red",
+    "couchdb",
+    "database",
+    "crud"
+  ],
+  "author": "kanr",
+  "license": "MIT",
+  "node-red": {
+    "nodes": {
+      "couchdb-server": "src/nodes/server/couchdb-server.js",
+      "couchdb-insert": "src/nodes/insert/couchdb-insert.js",
+      "couchdb-get": "src/nodes/get/couchdb-get.js",
+      "couchdb-query": "src/nodes/query/couchdb-query.js",
+      "couchdb-update": "src/nodes/update/couchdb-update.js",
+      "couchdb-create-db": "src/nodes/create-db/couchdb-create-db.js",
+      "couchdb-delete-db": "src/nodes/delete-db/couchdb-delete-db.js",
+      "couchdb-list-dbs": "src/nodes/list-dbs/couchdb-list-dbs.js",
+      "couchdb-list-docs": "src/nodes/list-docs/couchdb-list-docs.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kanr/node-red-contrib-couchdb-nodes.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kanr/node-red-contrib-couchdb-nodes/issues"
+  },
+  "homepage": "https://github.com/kanr/node-red-contrib-couchdb-nodes#readme",
+  "devDependencies": {
+    "mocha": "^8.4.0",
+    "should": "^13.2.3"
+  },
+  "dependencies": {
+    "nano": "^10.0.0"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=10.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/nodes/create-db/couchdb-create-db.html

@@ -0,0 +1,87 @@
+<script type="text/javascript">
+  RED.nodes.registerType('couchdb-create-db', {
+    category: 'couchdb',
+    color: '#ff6b00',
+    defaults: {
+      name: { value: '' },
+      server: { type: 'couchdb-server', required: true },
+      dbname: { value: '' }
+    },
+    inputs: 1,
+    outputs: 2,
+    icon: 'db.png',
+    label: function() {
+      return this.name || 'CouchDB Create DB';
+    }
+  });
+</script>
+
+<script type="text/x-red" data-template-name="couchdb-create-db">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" placeholder="Create Database">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-server"><i class="fa fa-server"></i> Server</label>
+    <input type="text" id="node-input-server">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-dbname"><i class="fa fa-database"></i> Database Name</label>
+    <input type="text" id="node-input-dbname" placeholder="e.g. my-new-database">
+  </div>
+
+  <div class="form-tips">
+    <p><strong>Input:</strong> Database name from config or msg.dbname or msg.payload</p>
+    <p><strong>Output 1 (Success):</strong> msg with result and dbname</p>
+    <p><strong>Output 2 (Error):</strong> msg with error information</p>
+  </div>
+</script>
+
+<script type="text/x-red" data-help-name="couchdb-create-db">
+  <p>Creates a new database in CouchDB.</p>
+
+  <h3>Inputs</h3>
+  <dl class="message-properties">
+    <dt class="optional">dbname <span class="property-type">string</span></dt>
+    <dd>Database name to create (overrides node config if provided)</dd>
+    <dt class="optional">payload <span class="property-type">string</span></dt>
+    <dd>Database name if dbname not specified</dd>
+  </dl>
+
+  <h3>Outputs</h3>
+  <ol class="node-ports">
+    <li>Success Output
+      <dl class="message-properties">
+        <dt>result <span class="property-type">object</span></dt>
+        <dd>Result containing <code>ok: true</code></dd>
+        <dt>dbname <span class="property-type">string</span></dt>
+        <dd>The created database name</dd>
+      </dl>
+    </li>
+    <li>Error Output
+      <dl class="message-properties">
+        <dt>error <span class="property-type">object</span></dt>
+        <dd>Error details if creation fails (e.g., database already exists)</dd>
+      </dl>
+    </li>
+  </ol>
+
+  <h3>Details</h3>
+  <p>Creates a new database with the specified name. If the database already exists, 
+     an error will be returned on the second output.</p>
+
+  <h3>Database Naming Rules</h3>
+  <ul>
+    <li>Must begin with a lowercase letter</li>
+    <li>Can contain lowercase letters (a-z), digits (0-9), and special characters (_, $, (, ), +, -, /)</li>
+    <li>Cannot start with an underscore (_) unless it's a system database</li>
+  </ul>
+
+  <h3>Example</h3>
+  <pre>
+msg.dbname = "my-application-db";
+return msg;
+  </pre>
+</script>

package/src/nodes/create-db/couchdb-create-db.js

@@ -0,0 +1,52 @@
+module.exports = function(RED) {
+  function CouchDBCreateDBNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    const serverConfig = RED.nodes.getNode(config.server);
+    if (!serverConfig) {
+      node.error("CouchDB server not configured");
+      return;
+    }
+
+    const nano = require('nano');
+    const url = `http://${serverConfig.username}:${serverConfig.password}@${serverConfig.hostname}:${serverConfig.port}`;
+    const couchdb = nano(url);
+
+    node.on("input", function(msg) {
+      const dbName = config.dbname || msg.dbname || msg.payload;
+
+      if (!dbName) {
+        node.error("Database name not specified", msg);
+        node.status({fill: "red", shape: "ring", text: "no database name"});
+        return;
+      }
+
+      node.status({fill: "blue", shape: "dot", text: "creating..."});
+
+      couchdb.db.create(dbName, (err, body) => {
+        if (err) {
+          node.error(`Create database failed: ${err.message}`, msg);
+          node.status({fill: "red", shape: "ring", text: "failed"});
+          msg.error = {
+            message: err.message,
+            statusCode: err.statusCode,
+            reason: err.reason
+          };
+          node.send([null, msg]);
+        } else {
+          node.status({fill: "green", shape: "dot", text: "created"});
+          msg.result = body;
+          msg.dbname = dbName;
+          node.send([msg, null]);
+        }
+      });
+    });
+
+    node.on("close", function() {
+      node.status({});
+    });
+  }
+
+  RED.nodes.registerType("couchdb-create-db", CouchDBCreateDBNode);
+};

package/src/nodes/delete-db/couchdb-delete-db.html

@@ -0,0 +1,108 @@
+<script type="text/javascript">
+  RED.nodes.registerType('couchdb-delete-db', {
+    category: 'couchdb',
+    color: '#ff6b00',
+    defaults: {
+      name: { value: '' },
+      server: { type: 'couchdb-server', required: true },
+      dbname: { value: '' },
+      confirmDelete: { value: false }
+    },
+    inputs: 1,
+    outputs: 2,
+    icon: 'db.png',
+    label: function() {
+      return this.name || 'CouchDB Delete DB';
+    }
+  });
+</script>
+
+<script type="text/x-red" data-template-name="couchdb-delete-db">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" placeholder="Delete Database">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-server"><i class="fa fa-server"></i> Server</label>
+    <input type="text" id="node-input-server">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-dbname"><i class="fa fa-database"></i> Database Name</label>
+    <input type="text" id="node-input-dbname" placeholder="e.g. database-to-delete">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-confirmDelete">
+      <input type="checkbox" id="node-input-confirmDelete" style="display:inline-block; width:auto; vertical-align:baseline;">
+      <span> Confirm Delete (Required)</span>
+    </label>
+  </div>
+
+  <div class="form-tips" style="background-color: #fff3cd; border-left: 4px solid #ffc107; padding: 10px;">
+    <p><strong>⚠️ WARNING:</strong> This will permanently delete the database and ALL its documents!</p>
+    <p><strong>Input:</strong> Database name from config or msg.dbname or msg.payload</p>
+    <p><strong>Output 1 (Success):</strong> msg with result and dbname</p>
+    <p><strong>Output 2 (Error):</strong> msg with error information</p>
+  </div>
+</script>
+
+<script type="text/x-red" data-help-name="couchdb-delete-db">
+  <p>Deletes a database from CouchDB.</p>
+
+  <h3>⚠️ WARNING</h3>
+  <p style="background-color: #fff3cd; padding: 10px; border-left: 4px solid #ffc107;">
+    <strong>This is a destructive operation!</strong><br>
+    Deleting a database will permanently remove the database and ALL documents within it.
+    This action cannot be undone.
+  </p>
+
+  <h3>Inputs</h3>
+  <dl class="message-properties">
+    <dt class="optional">dbname <span class="property-type">string</span></dt>
+    <dd>Database name to delete (overrides node config if provided)</dd>
+    <dt class="optional">payload <span class="property-type">string</span></dt>
+    <dd>Database name if dbname not specified</dd>
+    <dt class="optional">confirmDelete <span class="property-type">boolean</span></dt>
+    <dd>Set to <code>true</code> to confirm deletion (alternative to node config)</dd>
+  </dl>
+
+  <h3>Outputs</h3>
+  <ol class="node-ports">
+    <li>Success Output
+      <dl class="message-properties">
+        <dt>result <span class="property-type">object</span></dt>
+        <dd>Result containing <code>ok: true</code></dd>
+        <dt>dbname <span class="property-type">string</span></dt>
+        <dd>The deleted database name</dd>
+      </dl>
+    </li>
+    <li>Error Output
+      <dl class="message-properties">
+        <dt>error <span class="property-type">object</span></dt>
+        <dd>Error details if deletion fails (e.g., database not found)</dd>
+      </dl>
+    </li>
+  </ol>
+
+  <h3>Details</h3>
+  <p>Deletes the specified database. You must either:</p>
+  <ul>
+    <li>Check the "Confirm Delete" checkbox in the node configuration, OR</li>
+    <li>Set <code>msg.confirmDelete = true</code> in the flow</li>
+  </ul>
+
+  <h3>Safety</h3>
+  <p>The confirmation requirement helps prevent accidental database deletion. 
+     Consider using a switch or function node to add additional safety checks
+     before deleting production databases.</p>
+
+  <h3>Example Flow</h3>
+  <pre>
+// Function node before delete
+msg.dbname = "temp-database";
+msg.confirmDelete = true;  // Required for safety
+return msg;
+  </pre>
+</script>

package/src/nodes/delete-db/couchdb-delete-db.js

@@ -0,0 +1,59 @@
+module.exports = function(RED) {
+  function CouchDBDeleteDBNode(config) {
+    RED.nodes.createNode(this, config);
+    const node = this;
+
+    const serverConfig = RED.nodes.getNode(config.server);
+    if (!serverConfig) {
+      node.error("CouchDB server not configured");
+      return;
+    }
+
+    const nano = require('nano');
+    const url = `http://${serverConfig.username}:${serverConfig.password}@${serverConfig.hostname}:${serverConfig.port}`;
+    const couchdb = nano(url);
+
+    node.on("input", function(msg) {
+      const dbName = config.dbname || msg.dbname || msg.payload;
+
+      if (!dbName) {
+        node.error("Database name not specified", msg);
+        node.status({fill: "red", shape: "ring", text: "no database name"});
+        return;
+      }
+
+      // Warning: Destructive operation
+      if (config.confirmDelete === false && !msg.confirmDelete) {
+        node.error("Delete operation requires confirmation", msg);
+        node.status({fill: "yellow", shape: "ring", text: "not confirmed"});
+        return;
+      }
+
+      node.status({fill: "blue", shape: "dot", text: "deleting..."});
+
+      couchdb.db.destroy(dbName, (err, body) => {
+        if (err) {
+          node.error(`Delete database failed: ${err.message}`, msg);
+          node.status({fill: "red", shape: "ring", text: "failed"});
+          msg.error = {
+            message: err.message,
+            statusCode: err.statusCode,
+            reason: err.reason
+          };
+          node.send([null, msg]);
+        } else {
+          node.status({fill: "green", shape: "dot", text: "deleted"});
+          msg.result = body;
+          msg.dbname = dbName;
+          node.send([msg, null]);
+        }
+      });
+    });
+
+    node.on("close", function() {
+      node.status({});
+    });
+  }
+
+  RED.nodes.registerType("couchdb-delete-db", CouchDBDeleteDBNode);
+};