jsonbadger 0.5.0

package/src/schema/path-introspection.js

@@ -0,0 +1,82 @@
+/*
+- Assumptions and trade-offs:
+- Introspection resolves declared FieldType paths plus nested object path metadata.
+*/
+export function create_path_introspection(parsed_schema) {
+	const parsed_value = parsed_schema ?? {};
+	const field_types = resolve_field_types_map(parsed_value);
+	const object_paths = resolve_object_paths(parsed_value);
+
+	return {
+		field_types,
+		object_paths
+	};
+}
+
+export function get_path_field_type(path_introspection, path_name) {
+	if(!path_introspection || !path_name) {
+		return null;
+	}
+
+	const field_types = resolve_field_types_map(path_introspection);
+	return field_types[path_name] ?? null;
+}
+
+export function get_path_type(path_introspection, path_name) {
+	const field_type = get_path_field_type(path_introspection, path_name);
+
+	if(field_type) {
+		return field_type.instance;
+	}
+
+	const object_paths = resolve_object_paths(path_introspection);
+
+	if(object_paths.has(path_name)) {
+		return 'object';
+	}
+
+	return null;
+}
+
+export function is_array_root(path_introspection, path_name) {
+	if(!path_introspection || !path_name) {
+		return false;
+	}
+
+	const root_path = String(path_name).split('.')[0];
+	const root_field_type = get_path_field_type(path_introspection, root_path);
+
+	if(!root_field_type) {
+		return false;
+	}
+
+	return root_field_type.instance === 'Array';
+}
+
+function resolve_field_types_map(value) {
+	if(!value || typeof value !== 'object') {
+		return Object.create(null);
+	}
+
+	const field_types = value.field_types;
+
+	if(field_types && typeof field_types === 'object') {
+		return field_types;
+	}
+
+	return Object.create(null);
+}
+
+function resolve_object_paths(value) {
+	if(!value) {
+		return new Set();
+	}
+
+	const object_paths = value.object_paths;
+
+	if(object_paths instanceof Set) {
+		return object_paths;
+	}
+
+	return new Set();
+}

package/src/schema/schema-compiler.js

@@ -0,0 +1,212 @@
+/*
+Assumptions and trade-offs:
+- Validation/casting is FieldType-driven and unknown payload keys are preserved.
+- Error aggregation mirrors abortEarly=false behavior with deterministic per-path detail records.
+*/
+import field_definition_parser from '#src/schema/field-definition-parser.js';
+import {
+	create_path_introspection,
+	get_path_field_type,
+	get_path_type as resolve_path_type,
+	is_array_root as resolve_is_array_root
+} from '#src/schema/path-introspection.js';
+import {has_own} from '#src/utils/object.js';
+export default function schema_compiler(schema_definition) {
+	const parsed_schema = field_definition_parser(schema_definition || {});
+	const path_introspection = create_path_introspection(parsed_schema);
+	const field_types = path_introspection.field_types;
+	const sorted_paths = Object.keys(field_types).sort(sort_paths_by_depth);
+
+	return {
+		validate: function (payload) {
+			return validate_payload(payload, sorted_paths, field_types);
+		},
+		path: function (path_name) {
+			return get_path_field_type(path_introspection, path_name);
+		},
+		get_path_type: function (path_name) {
+			return resolve_path_type(path_introspection, path_name);
+		},
+		is_array_root: function (path_name) {
+			return resolve_is_array_root(path_introspection, path_name);
+		},
+		describe: function () {
+			return {
+				paths: Object.keys(field_types),
+				objects: Array.from(path_introspection.object_paths)
+			};
+		}
+	};
+}
+
+function validate_payload(payload, sorted_paths, field_types) {
+	if(payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+		return {
+			value: payload,
+			error: {
+				details: [{
+					path: '',
+					code: 'validation_error',
+					message: 'Schema validation failed',
+					type: 'object'
+				}]
+			}
+		};
+	}
+
+	const result_payload = clone_value(payload);
+	const detail_list = [];
+	let path_index = 0;
+
+	while(path_index < sorted_paths.length) {
+		const path_name = sorted_paths[path_index];
+		const field_type = field_types[path_name];
+		const path_segments = path_name.split('.');
+		const current_path_state = read_path(result_payload, path_segments);
+		const current_value = current_path_state.exists ? current_path_state.value : undefined;
+		let normalized_value = undefined;
+
+		try {
+			normalized_value = field_type.normalize(current_value, {path: path_name});
+		} catch(error) {
+			detail_list.push(format_field_error(path_name, error));
+			path_index += 1;
+			continue;
+		}
+
+		if(normalized_value === undefined) {
+			path_index += 1;
+			continue;
+		}
+
+		write_path(result_payload, path_segments, normalized_value);
+		path_index += 1;
+	}
+
+	if(detail_list.length > 0) {
+		return {
+			value: result_payload,
+			error: {
+				details: detail_list
+			}
+		};
+	}
+
+	return {
+		value: result_payload,
+		error: null
+	};
+}
+
+function sort_paths_by_depth(left_path, right_path) {
+	const left_depth = left_path.split('.').length;
+	const right_depth = right_path.split('.').length;
+
+	if(left_depth !== right_depth) {
+		return left_depth - right_depth;
+	}
+
+	return left_path.localeCompare(right_path);
+}
+
+function format_field_error(path_name, error) {
+	const error_message = error && error.message ? error.message : 'Schema validation failed';
+	const error_code = error && error.code ? error.code : 'validation_error';
+
+	return {
+		path: path_name,
+		code: error_code,
+		message: error_message,
+		type: error_code
+	};
+}
+
+function read_path(root_object, path_segments) {
+	let current_value = root_object;
+	let segment_index = 0;
+
+	while(segment_index < path_segments.length) {
+		const segment_value = path_segments[segment_index];
+
+		if(current_value === null || typeof current_value !== 'object' || !has_own(current_value, segment_value)) {
+			return {
+				exists: false,
+				value: undefined
+			};
+		}
+
+		current_value = current_value[segment_value];
+		segment_index += 1;
+	}
+
+	return {
+		exists: true,
+		value: current_value
+	};
+}
+
+function write_path(root_object, path_segments, next_value) {
+	let current_value = root_object;
+	let segment_index = 0;
+
+	while(segment_index < path_segments.length) {
+		const segment_value = path_segments[segment_index];
+		const is_leaf = segment_index === path_segments.length - 1;
+
+		if(is_leaf) {
+			current_value[segment_value] = next_value;
+			return;
+		}
+
+		// TODO: implement a code review agent that catches these 
+		if(
+			!has_own(current_value, segment_value) ||
+			current_value[segment_value] === null ||
+			typeof current_value[segment_value] !== 'object' ||
+			Array.isArray(current_value[segment_value])
+		) {
+			current_value[segment_value] = {};
+		}
+
+		current_value = current_value[segment_value];
+		segment_index += 1;
+	}
+}
+
+function clone_value(value) {
+	if(Array.isArray(value)) {
+		const cloned_array = [];
+		let value_index = 0;
+
+		while(value_index < value.length) {
+			cloned_array.push(clone_value(value[value_index]));
+			value_index += 1;
+		}
+
+		return cloned_array;
+	}
+
+	if(value instanceof Date) {
+		return new Date(value.getTime());
+	}
+
+	if(Buffer.isBuffer(value)) {
+		return Buffer.from(value);
+	}
+
+	if(value && typeof value === 'object') {
+		const cloned_object = {};
+		const object_entries = Object.entries(value);
+		let entry_index = 0;
+
+		while(entry_index < object_entries.length) {
+			const object_entry = object_entries[entry_index];
+			cloned_object[object_entry[0]] = clone_value(object_entry[1]);
+			entry_index += 1;
+		}
+
+		return cloned_object;
+	}
+
+	return value;
+}

package/src/schema/schema.js

@@ -0,0 +1,234 @@
+import defaults from '#src/constants/defaults.js';
+
+import ValidationError from '#src/errors/validation-error.js';
+import schema_compiler from '#src/schema/schema-compiler.js';
+
+import {default_field_type_registry} from '#src/field-types/registry.js';
+import {assert_condition, assert_identifier, assert_path} from '#src/utils/assert.js';
+import {is_object, is_string} from '#src/utils/value.js';
+import {has_own} from '#src/utils/object.js';
+
+export default function Schema(schema_def, options) {
+	this.schema_def = schema_def || {};
+	this.options = Object.assign({}, defaults.schema_options, options || {});
+	this.compiled_schema = schema_compiler(this.schema_def);
+	this.schema_description = this.compiled_schema.describe();
+	this.indexes = [];
+
+	register_path_level_indexes(this, this.schema_def, '', default_field_type_registry);
+}
+
+Schema.prototype.validate = function (payload) {
+	const validation_result = this.compiled_schema.validate(payload);
+
+	if(validation_result.error) {
+		throw new ValidationError('Schema validation failed', validation_result.error.details);
+	}
+
+	return validation_result.value;
+};
+
+Schema.prototype.path = function (path_name) {
+	if(!this.compiled_schema || typeof this.compiled_schema.path !== 'function') {
+		return null;
+	}
+
+	return this.compiled_schema.path(path_name);
+};
+
+Schema.prototype.get_path_type = function (path_name) {
+	if(!this.compiled_schema || typeof this.compiled_schema.get_path_type !== 'function') {
+		return null;
+	}
+
+	return this.compiled_schema.get_path_type(path_name);
+};
+
+Schema.prototype.is_array_root = function (path_name) {
+	if(!this.compiled_schema || typeof this.compiled_schema.is_array_root !== 'function') {
+		return false;
+	}
+
+	return this.compiled_schema.is_array_root(path_name);
+};
+
+Schema.prototype.create_index = function (index_spec, index_options) {
+	const normalized_index_spec = normalize_index_spec(index_spec);
+	const normalized_index_options = normalize_index_options(index_options);
+
+	this.indexes.push({
+		index_spec: normalized_index_spec,
+		index_options: normalized_index_options
+	});
+
+	return this;
+};
+
+Schema.prototype.get_indexes = function () {
+	const index_definitions = [];
+	let index_position = 0;
+
+	while(index_position < this.indexes.length) {
+		const index_definition = this.indexes[index_position];
+		const index_spec = clone_index_spec(index_definition.index_spec);
+		const index_options = Object.assign({}, index_definition.index_options);
+
+		index_definitions.push({
+			index_spec: index_spec,
+			index_options: index_options
+		});
+		index_position += 1;
+	}
+
+	return index_definitions;
+};
+
+function register_path_level_indexes(schema_instance, schema_definition, parent_path, field_registry) {
+	const schema_entries = Object.entries(schema_definition);
+	let entry_position = 0;
+
+	while(entry_position < schema_entries.length) {
+		const schema_entry = schema_entries[entry_position];
+		const path_segment = schema_entry[0];
+		const field_definition = schema_entry[1];
+		const path_value = parent_path ? parent_path + '.' + path_segment : path_segment;
+
+		if(is_explicit_field_definition(field_definition, field_registry)) {
+			register_index_option(schema_instance, path_value, field_definition.index);
+			entry_position += 1;
+			continue;
+		}
+
+		if(is_plain_object(field_definition)) {
+			register_path_level_indexes(schema_instance, field_definition, path_value, field_registry);
+		}
+
+		entry_position += 1;
+	}
+}
+
+function is_explicit_field_definition(field_definition, field_registry) {
+	if(!is_plain_object(field_definition) || !has_own(field_definition, 'type')) {
+		return false;
+	}
+
+	const type_key = field_definition.type;
+
+	if(Array.isArray(type_key)) {
+		return true;
+	}
+
+	return field_registry.has_field_type(type_key);
+}
+
+function register_index_option(schema_instance, path_value, index_option) {
+	if(index_option === undefined || index_option === false) {
+		return;
+	}
+
+	if(index_option === true) {
+		schema_instance.create_index(path_value);
+		return;
+	}
+
+	if(index_option === 1 || index_option === -1) {
+		schema_instance.create_index({
+			[path_value]: index_option
+		});
+		return;
+	}
+
+	if(is_plain_object(index_option)) {
+		const index_options = Object.assign({}, index_option);
+		const direction_value = resolve_path_level_index_direction(path_value, index_options);
+
+		schema_instance.create_index({
+			[path_value]: direction_value
+		}, index_options);
+		return;
+	}
+
+	throw new Error('index option at path "' + path_value + '" must be true, false, 1, -1, or an options object');
+}
+
+function resolve_path_level_index_direction(path_value, index_options) {
+	let direction_value = 1;
+
+	if(has_own(index_options, 'direction')) {
+		direction_value = index_options.direction;
+		delete index_options.direction;
+	}
+
+	if(has_own(index_options, 'order')) {
+		direction_value = index_options.order;
+		delete index_options.order;
+	}
+
+	assert_condition(direction_value === 1 || direction_value === -1, 'index direction for path "' + path_value + '" must be 1 or -1');
+
+	return direction_value;
+}
+
+function normalize_index_spec(index_spec) {
+	if(is_string(index_spec)) {
+		assert_path(index_spec, 'index path');
+		return index_spec;
+	}
+
+	assert_condition(is_object(index_spec), 'index_spec must be a path string or an object map of paths to sort directions');
+
+	const index_entries = Object.entries(index_spec);
+	assert_condition(index_entries.length > 0, 'index_spec object must define at least one indexed path');
+
+	const normalized_spec = {};
+	let entry_position = 0;
+
+	while(entry_position < index_entries.length) {
+		const index_entry = index_entries[entry_position];
+		const path_value = index_entry[0];
+		const direction_value = index_entry[1];
+
+		assert_path(path_value, 'index path');
+		assert_condition(
+			direction_value === 1 || direction_value === -1,
+			'index direction for path "' + path_value + '" must be 1 or -1'
+		);
+		normalized_spec[path_value] = direction_value;
+		entry_position += 1;
+	}
+
+	return normalized_spec;
+}
+
+function normalize_index_options(index_options) {
+	if(index_options === undefined) {
+		return {};
+	}
+
+	assert_condition(is_object(index_options), 'index_options must be an object');
+
+	const normalized_options = Object.assign({}, index_options);
+
+	if(normalized_options.unique !== undefined) {
+		assert_condition(typeof normalized_options.unique === 'boolean', 'index_options.unique must be a boolean');
+	}
+
+	if(normalized_options.name !== undefined) {
+		assert_identifier(normalized_options.name, 'index_options.name');
+	}
+
+	return normalized_options;
+}
+
+function clone_index_spec(index_spec) {
+	if(is_string(index_spec)) {
+		return index_spec;
+	}
+
+	return Object.assign({}, index_spec);
+}
+
+function is_plain_object(value) {
+	return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+

package/src/sql/parameter-binder.js

@@ -0,0 +1,13 @@
+export function create_parameter_state(start_index) {
+	return {
+		params: [],
+		current_index: start_index || 1
+	};
+}
+
+export function bind_parameter(parameter_state, value) {
+	const placeholder = '$' + parameter_state.current_index;
+	parameter_state.params.push(value);
+	parameter_state.current_index += 1;
+	return placeholder;
+}

package/src/sql/sql-runner.js

@@ -0,0 +1,31 @@
+import debug_logger from '#src/debug/debug-logger.js';
+import QueryError from '#src/errors/query-error.js';
+import {get_debug_mode, get_pool} from '#src/connection/pool-store.js';
+
+export default async function sql_runner(sql_text, sql_params) {
+	const params = sql_params || [];
+	const debug_mode = get_debug_mode();
+	const pool_instance = get_pool();
+
+	debug_logger(debug_mode, 'sql_query', {
+		sql_text: sql_text,
+		params: params
+	});
+
+	try {
+		return await pool_instance.query(sql_text, params);
+	} catch(error) {
+		debug_logger(debug_mode, 'sql_error', {
+			sql_text: sql_text,
+			params: params,
+			message: error.message
+		});
+
+		throw new QueryError('SQL execution failed', {
+			sql_text: sql_text,
+			params: params,
+			cause: error.message
+		});
+	}
+}
+

package/src/utils/array.js

@@ -0,0 +1,31 @@
+const is_not_array = (value) => {
+	return !Array.isArray(value);
+};
+
+const is_array = (value) => {
+	return Array.isArray(value);
+};
+
+const to_array = (object) => {
+	if(Array.isArray(object)) {
+		return object;
+	}
+
+	if(object instanceof Set) {
+		return Array.from(object);
+	}
+
+	return object != null ? [object] : [];
+};
+
+export {
+	to_array,
+	is_array,
+	is_not_array
+};
+
+export default {
+	to_array,
+	is_array,
+	is_not_array
+};

package/src/utils/assert.js

@@ -0,0 +1,27 @@
+const identifier_pattern = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+const path_pattern = /^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*$/;
+
+export function assert_condition(condition_value, message) {
+	if(!condition_value) {
+		throw new Error(message || 'Assertion failed');
+	}
+}
+
+export function assert_identifier(identifier_value, label) {
+	const label_value = label || 'identifier';
+
+	assert_condition(typeof identifier_value === 'string', label_value + ' must be a string');
+	assert_condition(identifier_pattern.test(identifier_value), label_value + ' has invalid characters');
+}
+
+export function assert_path(path_value, label) {
+	const label_value = label || 'path';
+
+	assert_condition(typeof path_value === 'string', label_value + ' must be a string');
+	assert_condition(path_pattern.test(path_value), label_value + ' has invalid characters');
+}
+
+export function quote_identifier(identifier_value) {
+	assert_identifier(identifier_value, 'identifier');
+	return '"' + identifier_value + '"';
+}

package/src/utils/json-safe.js

@@ -0,0 +1,9 @@
+export function safe_json_stringify(value) {
+	try {
+		return JSON.stringify(value);
+	} catch(error) {
+		return '"[unserializable]"';
+	}
+}
+
+export default safe_json_stringify;

package/src/utils/json.js

@@ -0,0 +1,21 @@
+function jsonb_bigint_replacer(key, value) {
+	if(typeof value === 'bigint') {
+		return value.toString();
+	}
+
+	return value;
+}
+
+function jsonb_stringify(value) {
+	return JSON.stringify(value, jsonb_bigint_replacer);
+}
+
+export {
+	jsonb_stringify,
+	jsonb_bigint_replacer
+};
+
+export default {
+	jsonb_stringify,
+	jsonb_bigint_replacer
+};

package/src/utils/object-path.js

@@ -0,0 +1,33 @@
+import {assert_path} from '#src/utils/assert.js';
+
+export function split_dot_path(path_value) {
+	assert_path(path_value, 'path');
+	return path_value.split('.');
+}
+
+export function build_path_literal(path_segments) {
+	return '{' + path_segments.join(',') + '}';
+}
+
+export function build_nested_object(path_value, leaf_value) {
+	const path_segments = split_dot_path(path_value);
+	const root_object = {};
+	let current_object = root_object;
+	let path_index = 0;
+
+	while(path_index < path_segments.length) {
+		const path_segment = path_segments[path_index];
+		const is_leaf = path_index === path_segments.length - 1;
+
+		if(is_leaf) {
+			current_object[path_segment] = leaf_value;
+			break;
+		}
+
+		current_object[path_segment] = {};
+		current_object = current_object[path_segment];
+		path_index += 1;
+	}
+
+	return root_object;
+}