{"id":48734172,"url":"https://github.com/tiny-essentials/puddysql","last_synced_at":"2026-05-01T03:03:28.265Z","repository":{"id":302663875,"uuid":"969047708","full_name":"Tiny-Essentials/PuddySQL","owner":"Tiny-Essentials","description":"🍮 Powerful SQL toolkit for Node.js, built with flexibility and structure in mind. Easily manage SQLite3/PostgreSQL, advanced queries, smart tag systems, and full JSON-friendly filters.","archived":false,"fork":false,"pushed_at":"2026-04-29T06:19:25.000Z","size":28757,"stargazers_count":1,"open_issues_count":22,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-29T07:25:50.008Z","etag":null,"topics":["advanced-search","database","nodejs","postgres","postgresql","query-builder","sql","sql-builder","sql-query","sqlite","sqlite3","tag-system","tiny-essentials"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/puddysql","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tiny-Essentials.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"patreon":"JasminDreasond","ko_fi":"JasminDreasond"}},"created_at":"2025-04-19T09:08:04.000Z","updated_at":"2026-04-29T06:13:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"bbad2fe2-b0d9-476f-b298-fd9ad4e6d57c","html_url":"https://github.com/Tiny-Essentials/PuddySQL","commit_stats":null,"previous_names":["jasmindreasond/puddysql","tiny-essentials/puddysql"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/Tiny-Essentials/PuddySQL","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tiny-Essentials%2FPuddySQL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tiny-Essentials%2FPuddySQL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tiny-Essentials%2FPuddySQL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tiny-Essentials%2FPuddySQL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tiny-Essentials","download_url":"https://codeload.github.com/Tiny-Essentials/PuddySQL/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tiny-Essentials%2FPuddySQL/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32483405,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["advanced-search","database","nodejs","postgres","postgresql","query-builder","sql","sql-builder","sql-query","sqlite","sqlite3","tag-system","tiny-essentials"],"created_at":"2026-04-12T03:11:27.477Z","updated_at":"2026-05-01T03:03:28.259Z","avatar_url":"https://github.com/Tiny-Essentials.png","language":"JavaScript","readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"./md-assets/puddysql.jpg\" alt=\"banner\" /\u003e\n\u003cp\u003e\n    \u003ca href=\"https://discord.gg/TgHdvJd\"\u003e\u003cimg src=\"https://img.shields.io/discord/413193536188579841?color=7289da\u0026logo=discord\u0026logoColor=white\" alt=\"Discord server\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/puddysql\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/puddysql.svg?maxAge=3600\" alt=\"NPM version\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/puddysql\"\u003e\u003cimg src=\"https://img.shields.io/npm/dt/puddysql.svg?maxAge=3600\" alt=\"NPM downloads\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cp\u003e\n    \u003ca href=\"https://www.patreon.com/JasminDreasond\"\u003e\u003cimg src=\"https://img.shields.io/badge/donate-patreon-F96854.svg?logo=patreon\" alt=\"Patreon\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://ko-fi.com/jasmindreasond\"\u003e\u003cimg src=\"https://img.shields.io/badge/donate-ko%20fi-29ABE0.svg?logo=ko-fi\" alt=\"Ko-Fi\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://chain.so/address/BTC/bc1qnk7upe44xrsll2tjhy5msg32zpnqxvyysyje2g\"\u003e\u003cimg src=\"https://img.shields.io/badge/donate-bitcoin-F7931A.svg?logo=bitcoin\" alt=\"Bitcoin\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://chain.so/address/LTC/ltc1qchk520v4u8334n5dntmgeja55gc5g5rrkgpd4f\"\u003e\u003cimg src=\"https://img.shields.io/badge/donate-litecoin-345D9D.svg?logo=litecoin\" alt=\"Litecoin\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cp\u003e\n    \u003ca href=\"https://nodei.co/npm/puddysql/\"\u003e\u003cimg src=\"https://nodei.co/npm/puddysql.png?downloads=true\u0026stars=true\" alt=\"npm installnfo\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003c/div\u003e\n\n# 🍮 PuddySQL\n\n**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.\n\nBuilt 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.\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install puddysql\n```\n\n---\n\n## 🧱 Main Features\n\n* ✅ Safe, composable SQL queries with named methods\n* 🔍 Powerful nested filters using JSON logic (AND/OR, operators, etc.)\n* 🏷️ Built-in tag filtering engine for JSON/array-based fields\n* 🔗 Dynamic JOIN builder with alias support\n* 📃 Smart pagination with automatic counters\n* 🧪 Strong input validation and type safety\n\n### Build 📦\n\nTo get started, please install the project dependencies. It is **mandatory** to run the build command afterward to ensure the module works correctly:\n```bash\nnpm install\nnpm run build:essentials\n```\n\n---\n\n## 📚 Documentation\n\nFor API reference, check each module’s own documentation:\n\n👉 **See:** [`docs/README.md`](./docs/README.md)\n\n---\n\n## 🔧 Module Overview\n\n| Module             | Description                                 |\n| ------------------ | ------------------------------------------- |\n| `PuddySqlEngine`   | Low-level query runner with DB abstraction  |\n| `PuddySqlInstance` | Manages databases and table bindings        |\n| `PuddySqlQuery`    | High-level querying with filters and joins  |\n| `PuddySqlTags`     | Parses tag filters into safe SQL conditions |\n\n---\n\n## 🧪 Requirements\n\n* Node.js 18+ recommended\n* Works with:\n\n  * ✅ SQLite3\n  * ✅ PostgreSQL (via `pg` adapter)\n\n---\n\n## 🧭 Modules Menu\n\nThe `PuddySql` class is the main access point to all core features of the library.\nYou should not instantiate it directly — instead, use `PuddySql.Instance`.\n\nHere's a quick overview of what's available:\n\n| 📦 Static Property  | 🔍 Description                                                              |\n| ------------------- | --------------------------------------------------------------------------- |\n| `PuddySql.Instance` | 🎮 Main SQL client class for managing databases (PostgreSQL or SQLite3)     |\n| `PuddySql.Query`    | 🧠 Query builder and smart search engine with advanced filtering            |\n| `PuddySql.Tags`     | 🏷️ Flexible tag system parser (with support for JSON arrays, boosts, etc.)  |\n| `PuddySql.Events`   | 🎯 Event manager to attach lifecycle hooks to query logic                   |\n| `PuddySql.Utils`    | 🛠️ Useful utilities (object flattening, merge helpers, SQL formatters)      |\n| `PuddySql.pg`       | 🐘 PostgreSQL database engine (pg wrapper)                                  |\n| `PuddySql.sqlite3`  | 📀 SQLite3 engine for local/in-memory usage (sqlite3 wrapper)               |\n\n---\n\n## 🚀 Quick Example\n\nHere’s how to get started using **PuddySQL**:\n\n```js\nimport path from 'path';\nimport { fileURLToPath } from 'url';\nimport PuddySql from 'puddysql';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\n// 🎮 Create a new SQL instance\nconst db = new PuddySql.Instance();\n\n// 📡 Run queries\n(async () =\u003e {\n  await db.initSqlite3();\n\n  // Insert a new user\n  const table = await db.initTable({ name: 'tinytest', id: 'id' }, [\n      ['id', 'TEXT', 'PRIMARY KEY'],\n      ['prompt', 'TEXT'],\n      ['yay', 'BOOLEAN']\n  ]);\n\n  console.log('Set');\n  console.log(await table.set('1', { prompt: 'pudding', yay: true }));\n  console.log(await table.set('2', { prompt: 'cookie', yay: true }));\n  console.log(await table.set('3', { prompt: 'brigadeiro', yay: true }));\n  console.log(await table.set('4', { prompt: 'banana', yay: false }));\n  console.log(await table.set('5', { prompt: 'chocolate', yay: true }));\n\n  console.log('Get All');\n  console.log(await table.getAll());\n\n  // Find a user by ID\n  console.log('Get');\n  const user = await table.get(1);\n  console.log(user); // → { id: 1, prompt: 'pudding', yay: true }\n\n  // Get a paginated list\n  console.log('Search');\n  const data1 = await db.getTable('tinytest').search({\n      q: {\n        group: 'AND',\n        conditions: [{ column: 'prompt', value: 'pudding' }],\n      },\n    });\n\n  const data2 = await table.search({\n      q: {\n          group: 'OR',\n          conditions: [\n            { column: 'prompt', value: 'pudding' },\n            { column: 'yay', value: false },\n          ],\n      },\n    });\n\n  console.log(data1); \n  console.log(data2); \n})();\n```\n\n---\n\n## 🤝 Contributions\n\nFeel free to fork, contribute, and create pull requests for improvements! Whether it's a bug fix or an additional feature, contributions are always welcome.\n\n## 📝 License\n\nThis project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.\n\n\u003e 🧠 **Note**: This documentation was written by [ChatGPT](https://openai.com/chatgpt), an AI assistant developed by OpenAI, based on the project structure and descriptions provided by the repository author.  \n\u003e If you find any inaccuracies or need improvements, feel free to contribute or open an issue!\n\n---\n\n## 🔙 Back to Tiny Essentials\n\nDid you like this module? It’s part of the **Tiny Essentials** collection — a set of minimal yet powerful tools to make development easier.\n👉 [Click here to explore more Tiny Essentials modules](https://github.com/Tiny-Essentials/Tiny-Essentials)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\u003ca href=\"./md-assets/img/\"\u003e\u003cimg src=\"./md-assets/img/85382271-5cf7-4806-ab8c-921167c0d8d7.png\" height=\"300\" /\u003e\u003c/a\u003e\n\u003cbr/\u003e\nMade with tiny love!\n\u003c/div\u003e","funding_links":["https://patreon.com/JasminDreasond","https://ko-fi.com/JasminDreasond","https://www.patreon.com/JasminDreasond","https://ko-fi.com/jasmindreasond"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiny-essentials%2Fpuddysql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftiny-essentials%2Fpuddysql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiny-essentials%2Fpuddysql/lists"}