🍮 PuddySQL

PuddySQL is a modular and extensible SQL toolkit for Node.js — designed to make dynamic queries, filters, pagination, and tag-based searches easy, safe, and powerful.

Built with composability in mind, each part of PuddySQL focuses on one job while integrating smoothly with the others. Whether you're working with SQLite or PostgreSQL, this package helps you build robust, readable, and scalable query logic.

---

📦 Installation

npm install puddysql

---

🧱 Main Features

• ✅ Safe, composable SQL queries with named methods
• 🔍 Powerful nested filters using JSON logic (AND/OR, operators, etc.)
• 🏷️ Built-in tag filtering engine for JSON/array-based fields
• 🔗 Dynamic JOIN builder with alias support
• 📃 Smart pagination with automatic counters
• 🧪 Strong input validation and type safety

Build 📦

To get started, please install the project dependencies. It is mandatory to run the build command afterward to ensure the module works correctly:

npm install
npm run build:essentials

---

📚 Documentation

For API reference, check each module’s own documentation:

👉 See:docs/README.md

---

🔧 Module Overview

Module	Description
PuddySqlEngine	Low-level query runner with DB abstraction
PuddySqlInstance	Manages databases and table bindings
PuddySqlQuery	High-level querying with filters and joins
PuddySqlTags	Parses tag filters into safe SQL conditions

---

🧪 Requirements

• Node.js 18+ recommended

• Works with:

  • ✅ SQLite3
  • ✅ PostgreSQL (via pg adapter)

---

🧭 Modules Menu

The PuddySql class is the main access point to all core features of the library. You should not instantiate it directly — instead, use PuddySql.Instance.

Here's a quick overview of what's available:

📦 Static Property	🔍 Description
PuddySql.Instance	🎮 Main SQL client class for managing databases (PostgreSQL or SQLite3)
PuddySql.Query	🧠 Query builder and smart search engine with advanced filtering
PuddySql.Tags	🏷️ Flexible tag system parser (with support for JSON arrays, boosts, etc.)
PuddySql.Events	🎯 Event manager to attach lifecycle hooks to query logic
PuddySql.Utils	🛠️ Useful utilities (object flattening, merge helpers, SQL formatters)
PuddySql.pg	🐘 PostgreSQL database engine (pg wrapper)
PuddySql.sqlite3	📀 SQLite3 engine for local/in-memory usage (sqlite3 wrapper)

---

🚀 Quick Example

Here’s how to get started using PuddySQL:

importpathfrom'path';import{fileURLToPath}from'url';importPuddySqlfrom'puddysql';const__filename=fileURLToPath(import.meta.url);const__dirname=path.dirname(__filename);// 🎮 Create a new SQL instanceconstdb=newPuddySql.Instance();// 📡 Run queries(async()=>{awaitdb.initSqlite3();// Insert a new userconsttable=awaitdb.initTable({name: 'tinytest',id: 'id'},[['id','TEXT','PRIMARY KEY'],['prompt','TEXT'],['yay','BOOLEAN']]);console.log('Set');console.log(awaittable.set('1',{prompt: 'pudding',yay: true}));console.log(awaittable.set('2',{prompt: 'cookie',yay: true}));console.log(awaittable.set('3',{prompt: 'brigadeiro',yay: true}));console.log(awaittable.set('4',{prompt: 'banana',yay: false}));console.log(awaittable.set('5',{prompt: 'chocolate',yay: true}));console.log('Get All');console.log(awaittable.getAll());// Find a user by IDconsole.log('Get');constuser=awaittable.get(1);console.log(user);// → { id: 1, prompt: 'pudding', yay: true }// Get a paginated listconsole.log('Search');constdata1=awaitdb.getTable('tinytest').search({q: {group: 'AND',conditions: [{column: 'prompt',value: 'pudding'}],},});constdata2=awaittable.search({q: {group: 'OR',conditions: [{column: 'prompt',value: 'pudding'},{column: 'yay',value: false},],},});console.log(data1);console.log(data2);})();

---

🤝 Contributions

Feel free to fork, contribute, and create pull requests for improvements! Whether it's a bug fix or an additional feature, contributions are always welcome.

📝 License

This project is licensed under the LGPL-3.0 License - see the LICENSE file for details.

🧠 Note: This documentation was written by ChatGPT, an AI assistant developed by OpenAI, based on the project structure and descriptions provided by the repository author.
If you find any inaccuracies or need improvements, feel free to contribute or open an issue!

---

🔙 Back to Tiny Essentials

Did you like this module? It’s part of the Tiny Essentials collection — a set of minimal yet powerful tools to make development easier. 👉 Click here to explore more Tiny Essentials modules

---

Made with tiny love!