π¦ HBH-DBMS
Overview
HBH-DBMS is a scalable, chunk-based, file-oriented DBMS for Node.js, designed to handle large datasets with safe traversal, deterministic paths, and zero external database dependency. HBH-DBMS is not just a DB layer β it is a complete filesystem database ecosystem designed for massive scale, clean hierarchy, and predictable storage. A lightweight, file-based DBMS for Node.js that manages JSON data, user files, content, channels, and configurations without requiring a traditional database (MySQL, MongoDB, etc).
hbh-dbmsis designed for backend developers who want simple, structured, and scalable file-based storage with modular services. File-Based Database Management System for Node.js HBH-DBMS is a hierarchical, file-based DBMS designed for Node.js applications where you want: It is a structured, chunk-oriented, traversal-safe DBMS designed to scale to very large datasets without filesystem collapse. HBH-DBMS is a modern, large-scale, file-based Database Management System for Node.js, built for developers who want:
- β No MongoDB / MySQL
- β Predictable filesystem storage
- β Predictable file structure
- β Massive scale support
- β Chunk-based directory distribution
- β Lazy folder creation
- β Deterministic paths
- β Clean testing & scripting usage
- β Human-readable JSON storage
- β Full CRUD with hierarchy
- β Easy testing & debugging
β‘ This is NOT a native JSON-file database. HBH-DBMS is engineered for real-world scale.
It is especially useful for:
- CMS systems
- SaaS backends
- Content platforms
- Admin panels
- Rapid prototyping
β¨ Features
- π JSON-based database (no external DB required)
- π§© Modular & class-based architecture
- π User File Management (UFM)
- π§ Content, Channel & Product handling
- βοΈ Config & Infinite File Management
- π Advanced content searching & filtering
- π§Ή Safe delete & cleanup utilities
- π ESM-first (
type: module) - πͺΆ Lightweight & fast
π§ Core Philosophy
HBH-DBMS follows a strict hierarchy:
User
βββ Product
βββ Channel
βββ Content
Each layer:
- Is owned by its parent
- Lives inside its parent directory
- Cannot exist independently
- Is managed by a dedicated DB class
This guarantees:
- π Data integrity
- π§Ή Clean deletes
- β»οΈ Easy recovery
π₯ Key Design Principles (IMPORTANT)
1οΈβ£ Lazy Folder Creation (Very Important)
β User folder is NOT created immediately
Instead:
-
User identity is validated
-
Path is resolved
-
Folder is created only when required
-
Prevents:
- Empty folders
- Garbage structure
- Orphaned users
π This is why HBH-DBMS scales better than native file DBs.
2οΈβ£ Chunk-Based Storage (Large Scale Ready)
To avoid filesystem limits (10k+ folders problem), HBH-DBMS:
- Splits data into chunks
- Uses multi-level nesting
- Distributes load evenly
Example:
Users/
βββ Ae/
βββ Alice@example.com/
π This prevents:
- Slow directory reads
- OS inode pressure
- FS traversal slowdown
3οΈβ£ Deterministic Path Resolution
Every entity path is:
- Derived from its ID
- Deterministic
- Rebuildable at any time
Meaning:
- No central index dependency
- No corruption cascade
- Easy recovery
4οΈβ£ Strict Hierarchical Ownership
User
βββ Product
βββ Channel
βββ Content
Rules:
- β Product cannot exist without User
- β Channel cannot exist without Product
- β Content cannot exist without Channel
This guarantees:
- Data integrity
- Clean deletes
- No orphan files
π Real Folder Structure
db/
βββ users/
β βββ U0/
β β βββ <user-id>/
β β β βββ .inf -> JSON DATA
β β β βββ <product-id>/
β β β β βββ .inf -> JSON DATA
β β β β βββ @<channel-id>/
β β β β β βββ content.json
β β β β β βββ .inf -> JSON DATA
β β β β β βββ <content-type>/
π Chunk folders are auto-calculated π This allows millions of records without FS degradation
π§© Modular Internal Design
Each DB class handles only its responsibility:
| Module | Responsibility |
|---|---|
BaseDB |
Safe FS + JSON ops |
UserDB |
User resolution & traversal |
ProductDB |
Product ownership |
ChannelDB |
Channel capacity & limits |
ContentDB |
Content chunking |
Handle_ID |
ID normalization |
DeleteAll |
Controlled cleanup |
π‘οΈ Safe Traversal Strategy
Every operation follows this flow:
- Validate input
- Resolve deterministic path
- Traverse hierarchy safely
- Create folder only if needed
- Write JSON atomically
π No blind mkdir -p
π No unsafe recursion
π No overwriting without intent
π Large-Scale Readiness Summary
HBH-DBMS supports:
β Millions of users β Millions of contents β Parallel directory growth β Predictable performance β OS-safe FS traversal
Because:
- Chunking β
- Lazy creation β
- Deterministic paths β
- Strict hierarchy β
π₯ Installation
1npm install hbh-dbms
π§ Basic Concept
Instead of using a traditional database, HBH-DBMS stores data as structured JSON files, organized by:
- Users
- Products
- Channels
- Content
- Configurations
- Uploaded files
This makes it:
- Easy to debug
- Easy to migrate
- Easy to back up
π Package Entry
1import { DBMS, libs } from 'hbh-dbms';
π Library Structure
1hbh-dbms2βββ db/3β βββ BaseDB.js4β βββ UserDB.js5β βββ ProductDB.js6β βββ ChannelDB.js7β βββ ContentDB.js8β βββ UFM.js9β βββ ConfigManager.js10β βββ InfFileManager.js11β βββ DeleteAll.js12β βββ Handle_ID.js13β βββ ContentFinder/14βββ libs/15β βββ FSHelper.js16β βββ EmptyDIRRemover.js17β βββ .Helper.js18βββ index.js
π§± DBMS Module
1import { DBMS } from 'hbh-dbms';
β οΈ DBMS is NOT a constructor
It is a namespace that exposes multiple DB classes.
π§± Available DB Classes
1DBMS.BaseDB2DBMS.UserDB3DBMS.ProductDB4DBMS.ChannelDB5DBMS.ContentDB6DBMS.BaseDB7DBMS.UserFileManager
HBH-DBMS is designed to be used directly, just like this:
1const userDB = new DBMS.UserDB();2const productDB = new DBMS.ProductDB();3const channelDB = new DBMS.ChannelDB();4const contentDB = new DBMS.ContentDB();
This is the recommended and documented approach.
π§± BaseDB (Internal Engine)
1const base = new DBMS.BaseDB("custom/path");
Handles:
- Atomic JSON read/write
- Directory integrity
- Traversal protection
- Directory safety
- Atomic updates
β οΈ Normally used internally by all DB modules, but exposed for advanced users.
π€ UserDB
Manage user-related data.
Manages users as root entities.
1const userDB = new DBMS.UserDB();
β Create User
1await userDB.create(2 "Alice@example.com",3 {4 email: "Alice@example.com",5 Info: {6 Author: "Alice",7 password: "12345678"8 }9 }10);
π What happens internally:
- User directory created
Users/Ae/Alice@example.com/ data.jsonwritten- Duplicate IDs prevented
π Read User
1const user = await userDB.read("Alice@example.com");
βοΈ Rename User (Update ID)
1await userDB.update(2 "Alice@example.com",3 "AliceDemo@gmail.com"4);
β Renames folder β Keeps all nested data intact
βοΈ Update User Info
1await userDB.updateInfo(2 "AliceDemo@gmail.com",3 {4 id2: 123456,5 password: "1234@Alice"6 }7);
β Merges data β Does not overwrite existing keys
β Delete User
1await userDB.delete("AliceDemo@example.com");
Deletes:
- User
- Products
- Channels
- Content
- Files
π List Users
1const users = await userDB.list();
π¦ ProductDB
1const productDB = new DBMS.ProductDB('Alice@example.com');
Products are owned by users.
β Create Product
1await productDB.create("Product1");
π Path created:
/Users/Ae/Alice@example.com/Product1/
π Read Product
1await productDB.read("Product1");
βοΈ Rename Product
1await productDB.update("Product1","Product2");
β Delete Product
1await productDB.delete("Product2");
π List Products
1await productDB.list();
πΊ ChannelDB
Channels live inside products. Channels can contain content, posts, or media.
1const channelDB = new DBMS.ChannelDB('Alice@example.com', 'Product1');2channelDB.Limit = 2;
π Limit controls max channels inside product db.
β Create Channel
1await channelDB.create("Channel1");
π Path created:
1/Users/Ae/Alice@example.com/Product1/Channel1
π Read Channel
1await channelDB.read("Channel1");
βοΈ Rename Channel
1await channelDB.update("Channel1", "Channel2");
βοΈ Update Channel Info
1await channelDB.updateInfo(2 "Channel2",3 { author: "HashirAttari" }4);
π Find Channel
1await channelDB.find("Channel1");
π List Channels
1await channelDB.list();
β Delete Channel
1await channelDB.delete("Channel2");
π ContentDB
Used for all content, including blogs, posts, articles, and videos, in JSON format. Content exists inside channels.
1const contentDB = new DBMS.ContentDB(channelDB, 'Channel1');2contentDB.Limit = 2;
π Limit controls max content inside channel db.
β Create Content
1const contentID = await contentDB.create(2 type = "list" | 'tutorial',3 contentName = "First-Content",4 body = ["Hello", "User", "ALice"] | { Name: "Alice", message: 'Hello' }5);
π Path created:
1/Users/Ae/Alice@example.com/Product1/Channel1/${ContentType}/First-Content.json
π Read Content
1await contentDB.read(contentID);
βοΈ Update Content Body
1await contentDB.updateContent(2 contentID,3 ["Alice", "AliceDemo"]4);
βοΈ Update Content Info
1await contentDB.updateInfo(2 contentID,3 {4 tags: ["updated"],5 author: "New Author"6 }7);
β Delete Content
1await contentDB.delete(contentID);
π List Content
1await contentDB.list({type: 'list' | 'all'});
π Find Content
1await contentDB.find(contentID);
π UserFileManager
UserFileManager handles user file operations inside products, including uploads, downloads, renames, deletes, and recycle bin functionality.
1const ufm = new DBMS.UserFileManager("Alice@example.com");
π Works per user and integrates with UserDB and ProductDB.
π Files are isolated per product to maintain safety.
β Create / Upload File
1await ufm.upload(req, "Alice@example.com", "Product1", "rename");
-
Handles HTTP file uploads via
formidable. -
Supports collision modes:
'skip'β skip if file exists'overwrite'β replace existing'rename'β auto-rename new file
-
Validates quota (
maxBytes) before saving. -
Stores files in:
/Users/Ae/Alice@example.com/Product1/<fileName>
- Adds metadata and tracks usage in the productβs config.
π Read File
1const content = await ufm.readFileContent("Alice@example.com", "Product1", "myfile.txt");
- Returns text content only (binary files will throw an error).
βοΈ Update File
1await ufm.updateFileContent("Alice@example.com", "Product1", "myfile.txt", "Updated text");
- Replaces file content.
- Validates text content.
- Updates usage tracking.
β Delete File
1await ufm.deleteFile("Alice@example.com", "Product1", "myfile.txt");
- Deletes a file.
- Updates usage accordingly.
π¦ Delete All Files in Product
1await ufm.deleteAllFiles("Alice@example.com", "Product1");
- Deletes all files/folders inside a product.
- Skips .config folder.
- Resets usage in config.
π Rename / Move File
1await ufm.renameFile("Alice@example.com", "Product1", "old.txt", "new.txt");2await ufm.moveFile("Alice@example.com", "Product1", "old.txt", "folder/new.txt");
- Moves or renames files safely inside product directories.
- Validates safe paths.
π Create Folder
1await ufm.createFolder("Alice@example.com", "Product1", "newFolder");
- Creates a directory inside a product.
π Recycle Bin
- Move to Bin:
1await ufm.BinFile("Alice@example.com", "Product1", "file.txt");
- Recover File:
1await ufm.RecoverFile("Alice@example.com", "Product1", "file.txt.hbhbin");
- List Trash:
1const trashFiles = await ufm.ListTrash("Alice@example.com", "Product1");
- Empty Trash:
1await ufm.EmptyTrash("Alice@example.com", "Product1");
π List Files / Directories
1await ufm.listFlat("Alice@example.com", "Product1"); // flat list2await ufm.listTree("Alice@example.com", "Product1"); // tree structure3await ufm.listDir("Alice@example.com", "Product1"); // directories only
- Filters .config folders automatically.
- Returns full metadata for files in tree/flat listings.
π Usage Info
1const { used, limit } = await ufm.usage("Alice@example.com", "Product1");
usedβ total bytes usedlimitβ maximum allowed bytes (defaultMAX_USER_STORAGE_BYTES)
βοΈ Product Management
1await ufm.createProduct("Product1");2await ufm.deleteProduct("Product1");
- Creates a product with initial config.
- Deletes product safely, including files.
π¦ 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
| Name | Type | Description |
|---|---|---|
userPage |
Number | Page number (example: 1) |
userLimit |
Number | Users per page (example: 10) |
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
| Name | Description |
|---|---|
productName |
Product scope (example: "HBH-CMS") |
userPage |
User pagination (example: 1) |
userLimit |
Users per page (example: 10) |
channelPage |
Channel pagination (example: 1) |
channelLimit |
Channels per page (example: 10) |
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.Channelinternally
π 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
IDManagerfor efficient indexed resolution. - Returns
nullif 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
pageandlimit. - 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
IDProcessingErrorfor invalid IDs. - Returns
successanddatafields 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
| Option | Type | Description |
|---|---|---|
ProductName |
string | Name of the product to scan |
find |
string | Target content ID(s) to search |
findChannel |
string | Target channel name to search |
OutputDir |
string | Directory to store output JSON |
WantOutput |
boolean | If true, writes results to file |
logs |
boolean | If true, logs progress info |
onProgress |
function | Callback on partial results or progress updates |
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
β οΈ Error Handling
- All methods throw
Error - No silent failures
- File corruption prevented
1try {2 await userDB.create("", {});3} catch (e) {4 console.error(e.message);5}
π Why Use HBH-DBMS?
- β CMS
- β SaaS backends
- β Admin systems
- β Easy to deploy
- β No database setup
- β Fully customizable
- β Debug-first systems
- β File-based backends
- β Offline-friendly apps
- β Ideal for CMS, admin panels, APIs
- β Perfect for small-to-medium projects
β When NOT to Use
- β Very high-traffic apps
- β Heavy concurrent writes
- β Complex relational queries
- β Financial or banking systems
π License
ISC License Β© HBH
π¨βπ» Author
HBH / HashirAttari Built with β€οΈ for Node.js developers