jsonbadger 0.5.0

package/docs/query-translation.md

@@ -0,0 +1,98 @@
+# query translation
+
+This project compiles Mongo-like filters into PostgreSQL SQL over JSONB data.
+
+## base behavior
+
+- all model records are stored in one JSONB column (`data` by default)
+- dot paths are translated to PostgreSQL JSON operators (`->`, `->>`, `#>`, `#>>`)
+- filters are parameterized (`$1`, `$2`, ...) for query safety
+
+## scalar equality
+
+- `{ user_name: 'john' }` -> text extraction + `=`
+- `{ age: { $ne: 20 } }` -> text extraction + `!=`
+
+## numeric comparisons
+
+- `$gt`, `$gte`, `$lt`, `$lte` cast extracted text to `numeric`
+- invalid numeric inputs throw `query_error` before SQL execution
+- `bigint` query values are bound without `Number(...)` coercion to avoid precision loss
+
+## set and array operators
+
+- `$in`, `$nin` -> `ANY($n::text[])`
+- `$all` -> JSONB containment `@>` with JSON array param
+- `$size` -> `jsonb_array_length(...) = $n`
+- `$contains` -> JSONB containment `@>`
+- `$elem_match` -> `EXISTS (SELECT 1 FROM jsonb_array_elements(...) ...)`
+
+## JSONB key existence operators
+
+- `$has_key` -> `?`
+- `$has_any_keys` -> `?|`
+- `$has_all_keys` -> `?&`
+
+Top-level semantics note:
+- PostgreSQL key-existence operators only check keys at the top level of the left-hand JSONB value.
+- jsonbadger preserves that behavior exactly.
+- If the filter path is nested (for example `profile.city`), jsonbadger first extracts that nested JSONB value (`#>`), then applies the existence operator to the extracted value's top level.
+- jsonbadger does not emulate recursive/deep key search for these operators.
+
+## JSONPath operators
+
+- `$json_path_exists` -> `@?` with a `::jsonpath` parameter
+- `$json_path_match` -> `@@` with a `::jsonpath` parameter
+- invalid/empty JSONPath values fail before SQL execution
+
+## JSON update operators
+
+- `$set` -> `jsonb_set(target, path, value, true)`
+- `$insert` -> `jsonb_insert(target, path, value, insert_after)`
+- `$set_lax` -> `jsonb_set_lax(target, path, value, create_if_missing, null_value_treatment)`
+
+Update path behavior:
+- Dot paths are validated before SQL execution.
+- Nested numeric segments are allowed for JSON array index paths in updates (for example `tags.0`).
+- Conflicting update paths in a single `update_one(...)` call (same path or parent/child overlap) fail before SQL execution.
+
+## regex
+
+- `$regex` uses PostgreSQL regex operators:
+- `~` (case-sensitive)
+- `~*` when `$options` includes `i`
+
+## sort, limit, skip
+
+- sort values use `-1` for `DESC`, everything else as `ASC`
+- limit/skip only apply for non-negative numeric values
+
+
+## PostgreSQL capability map
+
+This table is the implementation-facing capability map for currently supported query/update operators over JSONB.
+
+| jsonbadger feature | PostgreSQL operator/function | Notes | Indexability expectation |
+| --- | --- | --- | --- |
+| scalar equality (`{ path: value }`, `$ne`) | JSON extraction (`->>`, `#>>`) + `=` / `!=` | Compares extracted text/scalar representation | Manual expression indexes required for fast path filtering/sorting; current schema index helpers do not auto-create these expression indexes |
+| numeric comparisons (`$gt`, `$gte`, `$lt`, `$lte`) | JSON extraction + `::numeric` + comparison | Invalid numeric inputs fail before SQL execution | Manual expression indexes may be used; no automatic expression-index creation |
+| `$in`, `$nin` | `= ANY($n::text[])` / `!= ALL(...)` over extracted text | Set membership over extracted scalar text | Manual expression indexes only |
+| `$contains` | `@>` | JSONB containment over extracted JSONB value | GIN on JSONB value is typically the relevant index strategy |
+| `$all` | `@>` (JSON array containment) | Encodes requested list as JSON array | GIN on JSONB value is typically the relevant index strategy |
+| `$size` | `jsonb_array_length(...)` | Array length equality | Usually expression-based optimization if needed; no auto-created support |
+| `$elem_match` | `jsonb_array_elements(...)` + nested predicates | Uses set-returning expansion | Often less index-friendly than direct containment; depends on query shape |
+| `$regex` | `~` / `~*` on extracted text | PostgreSQL regex semantics | Manual text/expression indexing strategy required; jsonbadger does not auto-create regex-specific indexes |
+| `$has_key` | `?` | Top-level key existence on the left JSONB value | GIN on JSONB value is the expected index family |
+| `$has_any_keys` | `?|` | Any-key existence | GIN on JSONB value is the expected index family |
+| `$has_all_keys` | `?&` | All-keys existence | GIN on JSONB value is the expected index family |
+| `$json_path_exists` | `@?` | JSONPath existence predicate | Can benefit from JSONB GIN indexing depending on operator class/query shape |
+| `$json_path_match` | `@@` | JSONPath predicate match | Can benefit from JSONB GIN indexing depending on operator class/query shape |
+| `update_one.$set` | `jsonb_set(...)` | Creates missing path segments when configured (`true`) | N/A (write-path function) |
+| `update_one.$insert` | `jsonb_insert(...)` | Supports `insert_after` and numeric array-index path segments | N/A (write-path function) |
+| `update_one.$set_lax` | `jsonb_set_lax(...)` | Supports `create_if_missing` + `null_value_treatment` | N/A (write-path function) |
+
+Index helper behavior (current implementation):
+- `schema.create_index('path')` creates a GIN index on the extracted JSONB path expression.
+- `schema.create_index({ path: 1 })` (and compound object specs) create BTREE indexes on extracted text path expressions.
+- Single-path string GIN indexes do not support `unique` in jsonbadger; object specs support `unique` because they compile to BTREE indexes.
+

package/index.js

@@ -0,0 +1,2 @@
+export { default } from './src/index.js';
+export * from './src/index.js';

package/package.json

@@ -0,0 +1,58 @@
+{
+	"name": "jsonbadger",
+	"version": "0.5.0",
+	"description": "JSONB query/model library for PostgreSQL",
+	"main": "index.js",
+	"type": "module",
+	"exports": {
+		".": "./index.js"
+	},
+	"imports": {
+		"#src/*": "./src/*",
+		"#test/*": "./test/*"
+	},
+	"files": [
+		"index.js",
+		"src",
+		"docs",
+		"README.md",
+		"LICENSE"
+	],
+	"engines": {
+		"node": ">=20"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/carlosjln/jsonbadger.git"
+	},
+	"license": "MIT",
+	"author": "Carlos López",
+	"keywords": [
+		"postgres",
+		"postgresql",
+		"jsonb",
+		"query-builder",
+		"schema-validation"
+	],
+	"publishConfig": {
+		"access": "public",
+		"tag": "next"
+	},
+	"dependencies": {
+		"pg": "^8.18.0"
+	},
+	"devDependencies": {
+		"joi": "^18.0.2",
+		"dotenv": "^17.3.1",
+		"jest": "^30.2.0"
+	},
+	"scripts": {
+		"jest-cli": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js --config jest.config.mjs",
+		"test": "npm run test-unit",
+		"test-unit": "npm run jest-cli -- --runInBand test/unit",
+		"test-integration": "npm run jest-cli -- --runInBand test/integration/postgres",
+		"test-all": "npm run test-unit && npm run test-integration",
+		"test-output": "npm run jest-cli -- --runInBand test/unit --json --outputFile=test/test-output.json",
+		"test-coverage": "npm run jest-cli -- --runInBand test/unit --coverage"
+	}
+}

package/src/connection/connect.js

@@ -0,0 +1,56 @@
+import {Pool} from 'pg';
+
+import defaults from '#src/constants/defaults.js';
+import debug_logger from '#src/debug/debug-logger.js';
+import {assert_condition} from '#src/utils/assert.js';
+import {assert_valid_id_strategy} from '#src/constants/id-strategies.js';
+import {scan_server_capabilities, assert_id_strategy_capability} from '#src/connection/server-capabilities.js';
+import {is_string} from '#src/utils/value.js';
+import {get_pool, has_pool, set_pool} from '#src/connection/pool-store.js';
+
+export default async function connect(uri, options) {
+	assert_condition(is_string(uri) && uri.length > 0, 'connection_uri is required');
+
+	if(has_pool()) {
+		return get_pool();
+	}
+
+	const final_options = Object.assign({}, defaults.connection_options, options);
+	const {debug, id_strategy, auto_index, ...pool_options} = final_options;
+
+	assert_valid_id_strategy(id_strategy);
+	assert_condition(typeof auto_index === 'boolean', 'auto_index must be a boolean');
+
+	const pool_instance = new Pool(Object.assign({}, pool_options, {connectionString: uri}));
+	let server_capabilities;
+
+	try {
+		await pool_instance.query('SELECT 1');
+		server_capabilities = await scan_server_capabilities(pool_instance);
+		assert_id_strategy_capability(id_strategy, server_capabilities);
+		set_pool(pool_instance, final_options, server_capabilities);
+	} catch(error) {
+		await close_pool_quietly(pool_instance);
+		throw error;
+	}
+
+	debug_logger(debug, 'connection_ready', {
+		max: pool_options.max,
+		server_version: server_capabilities.server_version,
+		supports_uuidv7: server_capabilities.supports_uuidv7
+	});
+
+	return pool_instance;
+}
+
+async function close_pool_quietly(pool_instance) {
+	if(!pool_instance || typeof pool_instance.end !== 'function') {
+		return;
+	}
+
+	try {
+		await pool_instance.end();
+	} catch(error) {
+		// Ignore cleanup failures so the original connection/capability error is preserved.
+	}
+}

package/src/connection/disconnect.js

@@ -0,0 +1,16 @@
+import debug_logger from '#src/debug/debug-logger.js';
+import {clear_pool, get_debug_mode, get_pool, has_pool} from '#src/connection/pool-store.js';
+
+export default async function disconnect() {
+	if(!has_pool()) {
+		return;
+	}
+
+	const debug_mode = get_debug_mode();
+	const pool_instance = get_pool();
+
+	await pool_instance.end();
+	clear_pool();
+
+	debug_logger(debug_mode, 'connection_closed', null);
+}

package/src/connection/pool-store.js

@@ -0,0 +1,46 @@
+import defaults from '#src/constants/defaults.js';
+
+const connection_state = {
+	pool_instance: null,
+	debug_mode: defaults.connection_options.debug,
+	connection_options: Object.assign({}, defaults.connection_options),
+	server_capabilities: null
+};
+
+export function has_pool() {
+	return connection_state.pool_instance !== null;
+}
+
+export function get_pool() {
+	if(connection_state.pool_instance) {
+		return connection_state.pool_instance;
+	}
+
+	throw new Error('jsonbadger is not connected. Call connect() first.');
+}
+
+export function set_pool(pool_instance, connection_options, server_capabilities) {
+	connection_state.pool_instance = pool_instance;
+	connection_state.connection_options = Object.assign({}, defaults.connection_options, connection_options || {});
+	connection_state.debug_mode = connection_state.connection_options.debug;
+	connection_state.server_capabilities = server_capabilities === null ? null : Object.freeze(Object.assign({}, server_capabilities));
+}
+
+export function clear_pool() {
+	connection_state.pool_instance = null;
+	connection_state.connection_options = Object.assign({}, defaults.connection_options);
+	connection_state.debug_mode = defaults.connection_options.debug;
+	connection_state.server_capabilities = null;
+}
+
+export function get_debug_mode() {
+	return connection_state.debug_mode;
+}
+
+export function get_connection_options() {
+	return Object.assign({}, connection_state.connection_options);
+}
+
+export function get_server_capabilities() {
+	return connection_state.server_capabilities;
+}

package/src/connection/server-capabilities.js

@@ -0,0 +1,59 @@
+import IdStrategies from '#src/constants/id-strategies.js';
+import {assert_condition} from '#src/utils/assert.js';
+
+const MIN_POSTGRES_NATIVE_UUIDV7_VERSION_NUM = 180000;
+
+async function scan_server_capabilities(pool_instance) {
+	assert_condition(pool_instance && typeof pool_instance.query === 'function', 'pool_instance.query is required');
+
+	const server_version_num_result = await pool_instance.query('SHOW server_version_num;');
+	const server_version_result = await pool_instance.query('SHOW server_version;');
+	const uuidv7_function_result = await pool_instance.query(
+		"SELECT to_regprocedure('uuidv7()') IS NOT NULL AS has_uuidv7_function;"
+	);
+
+	const server_version_num_text = server_version_num_result.rows?.[0]?.server_version_num;
+	const server_version = server_version_result.rows?.[0]?.server_version;
+	const has_uuidv7_function = uuidv7_function_result.rows?.[0]?.has_uuidv7_function === true;
+	const server_version_num = Number.parseInt(String(server_version_num_text), 10);
+
+	assert_condition(Number.isInteger(server_version_num), 'Unable to determine PostgreSQL server_version_num');
+	assert_condition(typeof server_version === 'string' && server_version.length > 0, 'Unable to determine PostgreSQL server_version');
+
+	const supports_uuidv7 = server_version_num >= MIN_POSTGRES_NATIVE_UUIDV7_VERSION_NUM && has_uuidv7_function;
+
+	return {
+		server_version: server_version,
+		server_version_num: server_version_num,
+		supports_uuidv7: supports_uuidv7
+	};
+}
+
+function assert_id_strategy_capability(id_strategy, server_capabilities) {
+	if(id_strategy !== IdStrategies.uuidv7) {
+		return;
+	}
+
+	assert_condition(
+		server_capabilities && typeof server_capabilities === 'object',
+		'PostgreSQL server capabilities are unavailable. Reconnect so jsonbadger can run compatibility checks for id_strategy=uuidv7.'
+	);
+
+	assert_condition(server_capabilities.supports_uuidv7 === true, build_uuidv7_capability_error(server_capabilities));
+}
+
+function build_uuidv7_capability_error(server_capabilities) {
+	const server_version = server_capabilities.server_version ?? 'unknown';
+	const server_version_num = server_capabilities.server_version_num ?? 'unknown';
+	const supports_uuidv7 = server_capabilities.supports_uuidv7 === true ? 'true' : 'false';
+
+	return 'id_strategy=uuidv7 requires PostgreSQL native uuidv7() support (PostgreSQL 18+). ' +
+		'Detected server_version=' + server_version + ', server_version_num=' + server_version_num +
+		', supports_uuidv7=' + supports_uuidv7 + '.';
+}
+
+export {
+	MIN_POSTGRES_NATIVE_UUIDV7_VERSION_NUM,
+	scan_server_capabilities,
+	assert_id_strategy_capability
+};

package/src/constants/defaults.js

@@ -0,0 +1,20 @@
+import IdStrategies from '#src/constants/id-strategies.js';
+
+const defaults = {
+	connection_options: {
+		max: 10,
+		debug: false,
+		auto_index: true,
+		id_strategy: IdStrategies.bigserial
+	},
+
+	schema_options: {},
+	model_options: {
+		table_name: null,
+		data_column: 'data',
+		auto_index: null,
+		id_strategy: null
+	}
+};
+
+export default defaults;

package/src/constants/id-strategies.js

@@ -0,0 +1,29 @@
+import {assert_condition} from '#src/utils/assert.js';
+
+const IdStrategies = Object.freeze({
+	bigserial: 'bigserial',
+	uuidv7: 'uuidv7'
+});
+
+const id_strategy_values = Object.freeze(Object.values(IdStrategies));
+
+function is_valid(id_strategy) {
+	return id_strategy_values.includes(id_strategy);
+}
+
+function id_strategy_error() {
+	return 'id_strategy must be one of: ' + id_strategy_values.join(', ');
+}
+
+// TODO: consider moving this to assert file
+function assert_valid_id_strategy(id_strategy) {
+	assert_condition(is_valid(id_strategy), id_strategy_error());
+}
+
+export {
+	IdStrategies,
+	is_valid,
+	assert_valid_id_strategy
+};
+
+export default IdStrategies;

package/src/debug/debug-logger.js

@@ -0,0 +1,15 @@
+import safe_json_stringify from '#src/utils/json-safe.js';
+
+export default function debug_logger(debug_mode, event_name, event_data) {
+	if(!debug_mode) {
+		return;
+	}
+
+	const log_entry = {
+		event_name: event_name,
+		event_data: event_data || null,
+		created_at: new Date().toISOString()
+	};
+
+	console.log('[jsonbadger][debug] ' + safe_json_stringify(log_entry));
+}

package/src/errors/query-error.js

@@ -0,0 +1,23 @@
+export default function QueryError(message, details) {
+	this.name = 'query_error';
+	this.message = message || 'Query failed';
+	this.details = details || null;
+
+	if(Error.captureStackTrace) {
+		Error.captureStackTrace(this, QueryError);
+	}
+}
+
+QueryError.prototype = Object.create(Error.prototype);
+QueryError.prototype.constructor = QueryError;
+
+QueryError.prototype.to_json = function () {
+	return {
+		success: false,
+		error: {
+			type: 'query_error',
+			message: this.message,
+			details: this.details
+		}
+	};
+};

package/src/errors/validation-error.js

@@ -0,0 +1,23 @@
+export default function ValidationError(message, details) {
+	this.name = 'validation_error';
+	this.message = message || 'Validation failed';
+	this.details = details || null;
+
+	if(Error.captureStackTrace) {
+		Error.captureStackTrace(this, ValidationError);
+	}
+}
+
+ValidationError.prototype = Object.create(Error.prototype);
+ValidationError.prototype.constructor = ValidationError;
+
+ValidationError.prototype.to_json = function () {
+	return {
+		success: false,
+		error: {
+			type: 'validation_error',
+			message: this.message,
+			details: this.details
+		}
+	};
+};

package/src/field-types/base-field-type.js

@@ -0,0 +1,140 @@
+/*
+Assumptions and trade-offs:
+- Universal options are normalized here, while runtime-only behaviors are stored for later phases.
+- Validation/casting fails fast per path and defers aggregation to schema_compiler.
+*/
+function BaseFieldType(path_value, options) {
+	this.path = path_value;
+	this.options = options || {};
+	this.instance = 'Mixed';
+	this.validators = [];
+	this.regExp = null;
+	this.enum_values = null;
+	this.register_universal_validators();
+}
+
+BaseFieldType.prototype.register_universal_validators = function () {
+	if(this.options.required !== undefined) {
+		this.validators.push({
+			kind: 'required'
+		});
+	}
+
+	if(typeof this.options.validate === 'function') {
+		this.validators.push({
+			kind: 'custom'
+		});
+	}
+};
+
+BaseFieldType.prototype.create_field_error = function (code_value, message, value) {
+	const field_error = new Error(message);
+	field_error.code = code_value;
+	field_error.path = this.path;
+	field_error.value = value;
+	return field_error;
+};
+
+BaseFieldType.prototype.is_required = function (context_value) {
+	const required_option = this.options.required;
+
+	if(typeof required_option === 'function') {
+		return Boolean(required_option.call(null, context_value || {}));
+	}
+
+	return required_option === true;
+};
+
+BaseFieldType.prototype.resolve_default = function (context_value) {
+	if(this.options.default === undefined) {
+		return undefined;
+	}
+
+	if(typeof this.options.default === 'function') {
+		return this.options.default.call(null, context_value || {});
+	}
+
+	return this.options.default;
+};
+
+BaseFieldType.prototype.apply_set = function (value, context_value) {
+	if(typeof this.options.set !== 'function') {
+		return value;
+	}
+
+	return this.options.set.call(null, value, context_value || {});
+};
+
+BaseFieldType.prototype.apply_get = function (value, context_value) {
+	if(typeof this.options.get !== 'function') {
+		return value;
+	}
+
+	return this.options.get.call(null, value, context_value || {});
+};
+
+BaseFieldType.prototype.cast = function (value) {
+	return value;
+};
+
+BaseFieldType.prototype.run_custom_validator = function (value, context_value) {
+	if(typeof this.options.validate !== 'function') {
+		return;
+	}
+
+	let validator_result = false;
+
+	try {
+		validator_result = this.options.validate.call(null, value, context_value || {});
+	} catch(error) {
+		const message_value = error && error.message ? error.message : 'Custom validator failed for path "' + this.path + '"';
+		throw this.create_field_error('validator_error', message_value, value);
+	}
+
+	if(!validator_result) {
+		throw this.create_field_error('validator_error', 'Custom validator failed for path "' + this.path + '"', value);
+	}
+};
+
+BaseFieldType.prototype.run_type_validators = function () {
+	return;
+};
+
+BaseFieldType.prototype.validate = function (value, context_value) {
+	this.run_custom_validator(value, context_value || {});
+	this.run_type_validators(value, context_value || {});
+};
+
+BaseFieldType.prototype.normalize = function (value, context_value) {
+	const normalized_context = context_value || {};
+	let current_value = value;
+
+	if(current_value === undefined) {
+		current_value = this.resolve_default(normalized_context);
+	}
+
+	if(current_value === undefined || current_value === null) {
+		if(this.is_required(normalized_context)) {
+			throw this.create_field_error('required_error', 'Path "' + this.path + '" is required', current_value);
+		}
+
+		return current_value;
+	}
+
+	current_value = this.apply_set(current_value, normalized_context);
+	current_value = this.cast(current_value, normalized_context);
+	this.validate(current_value, normalized_context);
+	return current_value;
+};
+
+BaseFieldType.prototype.to_introspection = function () {
+	return {
+		path: this.path,
+		instance: this.instance,
+		validators: this.validators,
+		regExp: this.regExp || null,
+		enum_values: this.enum_values || null
+	};
+};
+
+export default BaseFieldType;