crondb-driver 1.0.0

package/README.md

@@ -0,0 +1,16 @@
+# CronDB Node.js SDK
+
+The official asynchronous ORM driver for **CronDB**, a high-performance, temporal C++ database engine.
+
+Traditional architectures force you to build "split-brain" systems to handle time-based events: storing the data in a database while pushing the timers to an external task queue. 
+
+**CronDB unifies state and time.** You inject finite-state-machine (FSM) timers directly into your database rows. When a state naturally expires, the C++ engine's asynchronous threads instantly push a webhook to your Node.js server. 
+
+No polling. No external queues. Just one unified temporal engine.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install crondb

package/crondb.js

@@ -0,0 +1,159 @@
+const http = require('http');
+
+class CronDB {
+    /**
+     * Initialize the CronDB Client
+     * @param {string} host - The IP of the C++ Engine
+     * @param {number} port - The port the engine is listening on
+     */
+    constructor(host = '127.0.0.1', port = 8080) {
+        this.host = host;
+        this.port = port;
+        // Keep-Alive Agent to prevent TCP exhaustion during heavy FSM loads
+        this.agent = new http.Agent({ keepAlive: true, maxSockets: 100 });
+    }
+
+    /**
+     * Send a raw SQL command to the engine
+     * @param {string} sqlString - The CronDB SQL command
+     * @returns {Promise<Object|string>} - The JSON or String response
+     */
+    async query(sqlString) {
+        return new Promise((resolve, reject) => {
+            const options = {
+                hostname: this.host,
+                port: this.port,
+                path: '/query',
+                method: 'POST',
+                agent: this.agent, // Uses our connection pool
+                headers: {
+                    'Content-Type': 'text/plain',
+                    'Content-Length': Buffer.byteLength(sqlString)
+                }
+            };
+
+            const req = http.request(options, (res) => {
+                let data = '';
+                res.on('data', (chunk) => { data += chunk; });
+                res.on('end', () => {
+                    try {
+                        resolve(JSON.parse(data)); // Try to parse pure JSON
+                    } catch (e) {
+                        resolve(data); // Fallback for raw strings like "success!"
+                    }
+                });
+            });
+
+            req.on('error', (e) => reject(`[CronDB Connection Error]: ${e.message}`));
+            req.write(sqlString);
+            req.end();
+        });
+    }
+
+    // ==========================================================
+    // ORM LAYER (Object-Relational Mapping)
+    // ==========================================================
+
+    /**
+     * Insert a native JavaScript object into the database
+     * @param {string} tableName 
+     * @param {Object} dataObj - e.g., { name: "Lancelot", hp: 100 }
+     */
+     async insert(tableName, dataObj) {
+        let sql = `INSERT INTO ${tableName}`;
+        
+        for (const [key, value] of Object.entries(dataObj)) {
+            if (typeof value === 'number' || typeof value === 'boolean') {
+                // Numbers and booleans stay raw
+                sql += ` ${key}=${value}`;
+            } else if (typeof value === 'string') {
+                const trimmed = value.trim();
+                // Smart check: Is it a CronDB Temporal FSM? e.g. "( 'Alive' --> 'Dead' @ 5 s )"
+                if (trimmed.startsWith('(') && trimmed.endsWith(')')) {
+                    sql += ` ${key}=${trimmed}`; // Don't quote FSMs
+                } else {
+                    sql += ` ${key}='${value}'`; // Wrap normal strings in quotes
+                }
+            }
+        }
+        return await this.query(sql);
+    }
+
+    /**
+     * Attach a Webhook Listener to a Temporal Column
+     * @param {string} tableName - The target table
+     * @param {string} columnName - The column with the time-state
+     * @param {string} webhookUrl - Where the C++ engine should shoot the HTTP POST
+     * @param {string} [whereClause=null] - Optional condition (e.g., "pid = 5")
+     */
+     async listen(tableName, columnName, webhookUrl, whereClause = null) {
+        let sql = `LISTEN ${tableName} . ${columnName} --> '${webhookUrl}'`;
+        
+        // If the developer wants to listen to a specific row, append it!
+        if (whereClause) {
+            sql += ` WHERE ${whereClause}`;
+        }
+        
+        return await this.query(sql);
+    }
+
+    /**
+     * READ: Select rows from a table
+     * @param {string} tableName 
+     * @param {string} [whereClause=null] - Optional (e.g., "energy < 50")
+     */
+     async select(tableName, whereClause = null) {
+        let sql = `SELECT * FROM ${tableName}`;
+        if (whereClause) {
+            sql += ` WHERE ${whereClause}`;
+        }
+        return await this.query(sql);
+    }
+
+    /**
+     * UPDATE: Modify existing rows using a native JS object
+     * @param {string} tableName 
+     * @param {Object} dataObj - The fields to update (e.g., { status: "Dead", hp: 0 })
+     * @param {string} whereClause - Required for safety (e.g., "pid = 5")
+     */
+    async update(tableName, dataObj, whereClause) {
+        if (!whereClause) throw new Error("CronDB ORM: Update requires a WHERE clause to prevent accidental table wipes.");
+        
+        let sql = `UPDATE ${tableName} SET`;
+        let isFirst = true;
+
+        for (const [key, value] of Object.entries(dataObj)) {
+            if (!isFirst) sql += ","; // Optional: depending on if your C++ parser uses commas for UPDATE
+            isFirst = false;
+
+            if (typeof value === 'number' || typeof value === 'boolean') {
+                sql += ` ${key}=${value}`;
+            } else if (typeof value === 'string') {
+                const trimmed = value.trim();
+                // Smart check for Temporal FSMs
+                if (trimmed.startsWith('(') && trimmed.endsWith(')')) {
+                    sql += ` ${key}=${trimmed}`;
+                } else {
+                    sql += ` ${key}='${value}'`;
+                }
+            }
+        }
+        
+        sql += ` WHERE ${whereClause}`;
+        return await this.query(sql);
+    }
+
+    /**
+     * DELETE: Remove rows from a table
+     * @param {string} tableName 
+     * @param {string} whereClause - Required for safety
+     */
+    async delete(tableName, whereClause) {
+        if (!whereClause) throw new Error("CronDB ORM: Delete requires a WHERE clause.");
+        
+        let sql = `DELETE FROM ${tableName} WHERE ${whereClause}`;
+        return await this.query(sql);
+    }
+}
+
+module.exports = CronDB;

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "crondb-driver",
+  "version": "1.0.0",
+  "description": "The official Node.js ORM and connection driver for the CronDB temporal database engine.",
+  "main": "crondb.js",
+  "scripts": {
+    "test": "node test_sdk.js"
+  },
+  "keywords": [
+    "database",
+    "temporal",
+    "fsm",
+    "orm",
+    "crondb",
+    "events"
+  ],
+  "author": "Michael Tal",
+  "license": "ISC"
+}

package/test_sdk.js

@@ -0,0 +1,79 @@
+const CronDB = require('./crondb');
+const http = require('http');
+
+// 1. Spin up a tiny temporary web server to catch the temporal webhooks
+const catcher = http.createServer((req, res) => {
+    let body = '';
+    req.on('data', chunk => body += chunk.toString());
+    req.on('end', () => {
+        console.log(`\n🎯 [WEBHOOK CAUGHT] Node.js received: ${body}`);
+        res.writeHead(200);
+        res.end();
+    });
+});
+catcher.listen(3000);
+
+// 2. Initialize the SDK
+const db = new CronDB('127.0.0.1', 8080);
+
+// Helper function to pause our Node.js script so we can watch time pass
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+
+async function runIntegrationTest() {
+    console.log("=== STARTING CRONDB SDK INTEGRATION TEST ===\n");
+
+    try {
+        console.log("[Phase 1] Forging the schema (Raw Query)...");
+        let res = await db.query("CREATE TABLE warriors wid ApexInt name string hp int status string 4");
+        console.log("Engine Reply:", res);
+
+        console.log("\n[Phase 2] Arming the Webhook Listener...");
+        res = await db.listen('warriors', 'status', 'http://127.0.0.1:3000');
+        console.log("Engine Reply:", res);
+
+        console.log("\n[Phase 3] CREATE: Using ORM to Insert Data...");
+        // Normal JS Object
+        await db.insert('warriors', { 
+            name: 'Tank', 
+            hp: 200, 
+            status: 'Defending' 
+        });
+        
+        // Temporal FSM Object (Fires in 3 seconds!)
+        await db.insert('warriors', { 
+            name: 'Assassin', 
+            hp: 80, 
+            status: "('Hidden' --> 'Revealed' @ 3 s)" 
+        });
+        console.log("Engine Reply: Data successfully planted.");
+
+        console.log("\n[Phase 4] READ: Using ORM to view Data...");
+        let rows = await db.select('warriors');
+        console.log("Current State:", rows);
+
+        console.log("\n[Phase 5] UPDATE: Using ORM to modify Data...");
+        await db.update('warriors', { hp: 150 }, "name = 'Tank'");
+        console.log("Engine Reply: Tank HP updated to 150.");
+
+        console.log("\n[Phase 6] DELETE: Using ORM to drop Data...");
+        await db.delete('warriors', "name = 'Tank'");
+        console.log("Engine Reply: Tank deleted.");
+
+        console.log("\n[Phase 7] Waiting for Temporal Detonation (3 seconds)...");
+        console.log("The clock is ticking...");
+        await sleep(4000); // Wait 4 seconds to ensure the 3-second C++ timer pops
+
+        console.log("\n[Phase 8] Final Read to verify state changes...");
+        rows = await db.select('warriors');
+        console.log("Final State (Assassin should be Revealed):", rows);
+
+    } catch (err) {
+        console.error("\n❌ Test Failed:", err);
+    } finally {
+        console.log("\n=== TEST COMPLETE. SHUTTING DOWN ===");
+        catcher.close();
+        process.exit(0);
+    }
+}
+
+runIntegrationTest();