📦 db Module

The db object is a lightweight helper layer that exposes HBH-DBMS core classes through a simple functional API.

📌 It does not implement new database logic 📌 It is a shortcut interface for existing DBMS modules 📌 Ideal for controllers, routes, CMS systems, and services

---

📌 Import

          
            1import { db } from 'hbh-dbms';
          
        

---

🧱 Structure Overview

          
            1export const db = {2  user,3  product,4  channel,5  content,6  listall,7  findall,8  cms9};
          
        

---

👤 db.user()

Creates a new UserDB instance.

          
            1const userDB = db.user();
          
        

🔹 Internally calls: new UserDB() 🔹 Used for user CRUD operations and listing

---

📦 db.product(user)

Creates a ProductDB instance scoped to a user.

          
            1const productDB = db.product('Alice@example.com');
          
        

🔹 Internally calls: new ProductDB(user) 🔹 Products always belong to a user

---

📺 db.channel(user, product)

Creates a ChannelDB instance under a product.

          
            1const channelDB = db.channel('Alice@example.com', 'Product1');
          
        

🔹 Internally calls: new ChannelDB(user, product) 🔹 Channels cannot exist without a product and user

---

📝 db.content(channelInstance, channelName)

Creates a ContentDB instance under a channel.

          
            1const contentDB = db.content(channelDB, 'Channel1');
          
        

🔹 Internally calls: new ContentDB(channelInstance, channelName) 🔹 Used for posts, articles, tutorials, media, etc.

---

📃 db.listall 🔍 db.findall

The listall and findall modules provide high-level traversal utilities for HBH-DBMS. They are designed to safely scan the entire filesystem hierarchy without breaking DBMS rules.

📌 These utilities do not bypass DBMS 📌 They reuse DBMS pagination & limits 📌 Built for CMS, admin panels, dashboards, and search systems

---

📃 listall

listall is used to list entities across hierarchy levels using safe pagination traversal.

          
            1db.listall
          
        

Available Methods

          
            1listall.User2listall.Channel3listall.Content
          
        

---

👤 listall.User(options)

Lists users using paginated traversal.

          
            1await listall.User({2  userPage: 1,3  userLimit: 104});
          
        

Parameters

Response

          
            1{2  success: true,3  message: "Users fetched",4  data: [ "alice@example.com", "bob@example.com" ],5  pagination: { userPage: 1, userLimit: 10 }6}
          
        

Notes

• Internally uses UserDB.list()
• Safe for large datasets
• No eager filesystem traversal

---

📺 listall.Channel(options)

Lists channels across all users under a given product.

          
            1await listall.Channel({2  productName: "HBH-CMS",3  userPage: 1,4  userLimit: 10,5  channelPage: 1,6  channelLimit: 107});
          
        

Parameters

Response

          
            1{2  success: true,3  data: {4    "alice@example.com": ["Channel1", "Channel2"],5    "bob@example.com": ["News"]6  }7}
          
        

Notes

• Traverses User → Product → Channel
• Channel names are normalized
• Errors per user are safely skipped

---

📝 listall.Content(options)

Lists content across users, channels, and content types.

          
            1await listall.Content({2  productName: "HBH-CMS",3  userPage: 1,4  userLimit: 10,5  channelPage: 1,6  channelLimit: 10,7  contentPage: 1,8  contentLimit: 209});
          
        

Response

          
            1{2  success: true,3  data: {4    "content-id-1": { user: "alice@example.com", channel: "Channel1" },5    "content-id-2": { user: "bob@example.com", channel: "News" }6  }7}
          
        

Notes

• Traverses entire DB hierarchy
• Content types are auto-detected
• Designed for CMS indexing

---

🔍 findall

findall provides deep search utilities to locate entities without knowing their exact path.

          
            1db.findall
          
        

Available Methods

          
            1findall.User2findall.Channel3findall.Findchannel4findall.Content5findall.Findcontent
          
        

---

👤 findall.User(username)

Finds a user by ID using paginated scanning.

          
            1await findall.User("alice@example.com");
          
        

Behavior

• Scans user pages sequentially
• Stops immediately when found
• Safe for very large datasets

---

📺 findall.Channel or findall.Findchannel (channelName, options)

Finds a channel across all users under a product. Uses ChannelManager for indexed channel lookup.

          
            1await findall.Channel("Channel1", {2  productName: "HBH-CMS"3});
          
        

Response

          
            1{2  success: true,3  data: {4    user: "alice@example.com",5    channel: "Channel1"6  }7}
          
        

Notes

• Channel names are normalized
• Stops on first match
• Uses listall.Channel internally

---

📝 findall.Content or 🆔 findall.Findcontent (contentID, options)

Finds a content item anywhere in the DB. Uses IDManager for indexed content lookup.

          
            1await findall.Content("content-id-1", {2  productName: "HBH-CMS"3});
          
        

Behavior

• Traverses:

  User → Product → Channel → Content
  

• Auto-advances pagination

• Stops early on match

          
            1await findall.Findcontent("content-id-1", { productName: "HBH-CMS" });
          
        

Notes

• Direct ID resolution
• No filesystem scanning
• Most efficient content lookup method

---

🎯 Design Philosophy

✔ No unsafe recursion ✔ Pagination-based traversal ✔ Early-exit search ✔ CMS & admin friendly ✔ Deterministic & recoverable

📌 listall = enumeration 📌 findall = discovery

---

🧠 db.cms – CMS Utilities

A collection of helpers designed for content-driven and CMS-based systems. The cms module provides high-level CMS utilities for HBH-DBMS, focusing on content fetching, content lookup, and ID handling. It integrates multi-threaded scanning, pagination-safe traversal, and indexed lookup.

📌 Designed for CMS, dashboards, and large-scale content processing. 📌 Supports product-scoped content fetchers and ID-based direct content access. 📌 Optimized for multi-threaded content scanning using workers.

---

🖥️ fetchcontent (Product-Specific Content Fetchers)

fetchcontent provides asynchronous content fetching functions per product. Each function returns content in paginated chunks.

          
            1db.cms.fetchcontent.HBHCodes2db.cms.fetchcontent.HBHTube3db.cms.fetchcontent.CodeBuddy
          
        

Example Usage

          
            1const fetchNext = db.cms.fetchcontent.HBHCodes;3// Fetch next batch of content4const contents = await fetchNext();5console.log(contents);
          
        

Behavior

• Tracks internal pagination: userPage, channelPage, contentPage.
• Auto-advances pages when current batch is empty.
• Can resume from a given pagination index:

          
            1await fetchNext({ user: 2, channel: 1, content: 5 });
          
        

• Designed for CMS batch processing with large datasets.

---

🔍 findcontent(targetID, { productName })

Finds content by ID using indexed IDManager lookup.

          
            1const content = await db.cms.findcontent('content-id-123', { productName: 'CodeBuddy' });
          
        

Response

          
            1{2  success: true,3  data: {4    user: "alice@example.com",5    channel: "Channel1",6    content: { ... }7  }8}
          
        

Notes

• Uses IDManager for efficient indexed resolution.
• Returns null if content is not found.
• Avoids filesystem-wide traversal when possible.

---

🔍 findchannel(targetChannel, { productName })

Finds channel info by name using ChannelManager.

          
            1const channel = await db.cms.findchannel('Channel1', { productName: 'CodeBuddy' });
          
        

Response

          
            1{2  success: true,3  data: {4    user: "alice@example.com",5    channel: "Channel1"6  }7}
          
        

Notes

• Channel names are normalized internally.
• Stops on first match for efficiency.
• Uses listall traversal internally only if needed.

---

📄 getcontent({ page, limit, ProductName, username })

Fetches content in paginated form for a given product and user.

          
            1const pageData = await db.cms.getcontent({2  page: 1,3  limit: 50,4  ProductName: 'CodeBuddy',5  username: 'alice@example.com'6});
          
        

Notes

• Pagination-safe: Supports page and limit.
• Designed for UI dashboards, CMS listing, and admin views.

---

🆔 handleid(ids, ProductName)

Fetches content directly via content IDs. Supports single ID or array of IDs.

          
            1const result = await db.cms.handleid('D9.x.a.h', 'CodeBuddy');2const batch = await db.cms.handleid(['D9.x.a.h','D9.x.a.$'], 'CodeBuddy');
          
        

Behavior

• Uses ID-level parsing to determine hierarchy:

          
            1root → user → channel → content
          
        

• Supports wildcard $ to fetch all content under a channel.
• Throws structured errors via IDProcessingError for invalid IDs.
• Returns success and data fields for matched content.

Example Response

          
            1{2  success: true,3  data: {4    id: "D9.x.a.h",5    content: { title: "Hello World", ... },6    userName: "alice@example.com",7    channelName: "Channel1"8  }9}
          
        

---

🛠️ Worker-Based Content Scanning

The contentFinder function is an internal multi-threaded utility for CMS products.

Features

• Uses worker threads to scan directories concurrently.
• Tracks total content files and progress.
• Supports pause/resume events during scanning.
• Can stop early if a target content ID or channel is found.
• Writes output optionally to JSON for external processing.

Parameters

Example Usage

          
            1await contentFinder({2  ProductName: 'CodeBuddy',3  WantOutput: true,4  find: 'D9.x.a.h',5  logs: true,6  onProgress: (data) => console.log('Progress:', data)7});
          
        

---

🧭 Design Philosophy

✔ Product-scoped fetchers (fetchcontent) for CMS batch operations ✔ Direct content lookup (findcontent, handleid) using indexed resolution ✔ Worker-based multi-threaded scanning for large-scale content directories ✔ Safe pagination-based traversal, avoids full filesystem blocking ✔ Deterministic and recoverable: all fetches and searches are repeatable

---

If you want, I can now generate a full “CMS Reference” document with methods, parameters, examples, and detailed worker explanations in markdown just like the listall/findall documentation you shared. It would be ready for your docs site.

Do you want me to do that next?

---

🎯 Why This db Wrapper Exists

• ✔ Cleaner imports
• ✔ Functional API style
• ✔ Controller-friendly
• ✔ No tight class coupling
• ✔ Same DBMS power with less boilerplate

---