JsonBadger

JsonBadger is a Node.js library for working with complex JSON data in PostgreSQL through a schema-driven model API. Instead of building nested JSONB queries by hand, you define schemas and use document-style models, query operators, and persistence helpers.

Why did I create this utility?

I originally built my personal systems and small business client projects using MongoDB and Mongoose. Over time, that setup was no longer viable or cost-effective on shared hosting. I needed a solution that was more contained and budget-friendly. Since most shared hosting providers offer free, robust PostgreSQL databases, I created this utility to leverage PostgreSQL's jsonb fields as an alternative for document-based storage.

Table of Contents

• Install
• Examples (Quick Start)
• Examples Cheat Sheet
• Core Features
• Documentation
• Author
• License

Install

Requirements:

• Node.js >=20
• PostgreSQL

npm install jsonbadger

Examples (Quick Start)

import JsonBadger from 'jsonbadger';

// 1. Connect to database
const db_uri = 'postgresql://user:pass@localhost:5432/dbname';
const options = {
	debug: false,
	max: 10,
	ssl: false
};
const connection = await JsonBadger.connect(db_uri, options);

// 2. Define schema (FieldType format)
const user_schema = new JsonBadger.Schema({
	name: {type: String, required: true, index: true},
	age: {type: Number, min: 0, index: -1},
	type: {type: String},
	email: {type: String, index: {unique: true, name: 'idx_users_email_unique'}}
}, {
	identity: {
		type: JsonBadger.IDENTITY_TYPE.bigint,
		format: null,
		mode: JsonBadger.IDENTITY_MODE.fallback,
		generator: null
	},
	auto_index: true
});

// 3. Declare indexes on schema (path-level + schema-level compound index)
// Descriptor-form create_index(...) is how you define explicit index declarations.
user_schema.create_index({using: 'btree', paths: {name: 1, type: -1}});

// 4. Create model
const User = connection.model({
	name: 'User',
	schema: user_schema,
	table_name: 'users'
});

// 5. Run migrations manually
await User.ensure_table();
await User.ensure_indexes();

// 6. Save a document
const saved_user = await User.from({
	name: 'john',
	age: 30,
	type: 'admin'
}).save();
// returns: User document instance
// saved_user.to_json() -> { id, name, age, type, created_at, updated_at }

// 7. Find a document
const found_user = await User.find_one({
	name: 'john'
}).exec();
// returns: User document instance or null
// found_user?.to_json() -> { id, name, age, type, created_at, updated_at }

When using UUIDv7 ids, declare them through schema.options.identity. JsonBadger scans server capabilities during connect(...), binds the database path when native uuidv7() is available, and otherwise uses identity.generator when you provide one.

Examples Cheat Sheet

For a complete copy-paste operator and runtime cheat sheet (queries, updates, and document methods), see docs/examples.md.

For the document state flow from new Model(...) through save(), hydration, dirty tracking, and serialization, see docs/lifecycle.md.

Core Features

• JSONB-first: Model API designed specifically for PostgreSQL JSONB.
• Validation: FieldType-based schema validation built in.
• Querying: Mongo-style query operators such as $gt, $regex, $contains, and $elem_match.
• Runtime document APIs: get, set, alias virtuals, serialization helpers, mark_modified/dirty tracking, and immutable enforcement after save.
• JSON updates: update_one(...) supports implicit keys, $set, $unset, and $replace_roots.
• Migrations: Helpers for ensure_table, ensure_indexes, and ensure_model.
• Configurable row IDs: use schema.options.identity with IDENTITY_TYPE, IDENTITY_FORMAT, and IDENTITY_MODE.
• ID create semantics: bigint mode stays database-generated by default. UUIDv7 binds to the database path or the application path depending on server capability and identity.generator.
• Timestamp helper semantics: created_at and updated_at are helper fields. See docs/lifecycle.md for insert and update behavior.
• Configurable index lifecycle: auto_index is a schema option that controls whether ensure_model() also ensures indexes.
• UUIDv7 compatibility checks: JsonBadger checks support automatically and fails early when unavailable.
• Document instance returns: data-returning methods return document instances with top-level base fields (id, created_at, updated_at), and .to_json() / .$serialize() for plain-object snapshots.
• Modern: Native ESM package.

Documentation

• docs/api/index.md
• docs/api/model.md (model construction, queries, persistence, and document methods)
• docs/api/schema.md
• docs/api/query-builder.md
• docs/api/connection.md (connection API, lifecycle, and shared-connection examples)
• docs/api/field-types.md
• docs/examples.md (complete example cheat sheet for queries, updates, and runtime document methods)
• docs/lifecycle.md (document phases, hydration/save flow, dirty tracking, and serialization)
• docs/advanced/query-translation.md (advanced PostgreSQL reference for operators and query behavior)
• docs/local-integration-testing.md
• CHANGELOG.md for release notes and version history

Author

Carlos López

• GitHub: @carlosjln

License

MIT. See LICENSE.