jsonbadger 0.5.0 → 0.6.1

package/src/connection/connection.js

@@ -0,0 +1,128 @@
+import debug_logger from '#src/debug/debug-logger.js';
+import defaults from '#src/constants/defaults.js';
+import ModelOverwriteError from '#src/errors/model-overwrite-error.js';
+import model_factory from '#src/model/factory/index.js';
+import {assert_condition, assert_identifier} from '#src/utils/assert.js';
+import {are_equal} from '#src/utils/object.js';
+import {pluralize} from '#src/utils/string.js';
+import {is_function, is_plain_object} from '#src/utils/value.js';
+
+/**
+ * Stores connection-owned runtime state and model registration.
+ *
+ * @param {*} pool_instance Backing pg pool instance.
+ * @param {object} options Normalized connection options.
+ * @param {*} server_capabilities Capability snapshot for this pool.
+ * @returns {void}
+ */
+function Connection(pool_instance, options, server_capabilities) {
+	this.pool_instance = pool_instance;
+	this.options = Object.assign({}, defaults.connection_options, options);
+	this.server_capabilities = server_capabilities || null;
+	this.models = {};
+}
+
+/**
+ * Registers a model on this connection.
+ *
+ * @param {object} model_definition Model registration input.
+ * @param {string} model_definition.name Model registry key.
+ * @param {*} model_definition.schema Schema instance.
+ * @param {string} [model_definition.table_name] Explicit table name override.
+ * @returns {Function}
+ * @throws {Error} When the definition is invalid.
+ * @throws {ModelOverwriteError} When an existing model is redefined with different schema/options.
+ */
+Connection.prototype.model = function (model_definition) {
+	assert_condition(is_plain_object(model_definition), 'model_definition is required');
+
+	const model_name = model_definition.name;
+	const schema_instance = model_definition.schema;
+
+	assert_identifier(model_name, 'model_definition.name');
+
+	const existing_model = this.models[model_name];
+	const model_options = create_model_options(model_definition);
+	const requested_definition = {
+		name: model_name,
+		schema_instance,
+		model_options
+	};
+
+	if(existing_model) {
+		assert_model_definition_match(existing_model, requested_definition);
+		return existing_model;
+	}
+
+	const Model = model_factory(model_name, schema_instance, model_options, this);
+
+	this.models[model_name] = Model;
+	return Model;
+};
+
+/**
+ * Closes the underlying pool for this connection.
+ *
+ * @returns {Promise<void>}
+ */
+Connection.prototype.disconnect = async function () {
+	const pool_instance = this.pool_instance;
+
+	if(!pool_instance || !is_function(pool_instance.end)) {
+		return;
+	}
+
+	await pool_instance.end();
+
+	debug_logger(this.options.debug, 'connection_closed', null);
+};
+
+/**
+ * Builds the model options passed into the existing model factory bridge.
+ *
+ * @param {object} model_definition Model registration input.
+ * @returns {object}
+ */
+function create_model_options(model_definition) {
+	const {name, schema, ...model_options} = model_definition;
+	void name;
+	void schema;
+
+	if(!model_options.table_name) {
+		model_options.table_name = pluralize(model_definition.name);
+	}
+
+	return model_options;
+}
+
+/**
+ * Enforces idempotent model registration on a connection.
+ *
+ * Re-registering the same model name is allowed only when schema and
+ * normalized model options match the existing model.
+ *
+ * @param {Function} existing_model
+ * @param {object} requested_definition
+ * @throws {ModelOverwriteError}
+ */
+function assert_model_definition_match(existing_model, requested_definition) {
+	const {
+		name,
+		schema_instance,
+		model_options
+	} = requested_definition;
+
+	if(existing_model.schema !== schema_instance) {
+		throw new ModelOverwriteError('model "' + name + '" is already registered with a different schema', {
+			name
+		});
+	}
+
+	if(!are_equal(existing_model.options, model_options)) {
+		throw new ModelOverwriteError('model "' + name + '" is already registered with different model options', {
+			name
+		});
+	}
+}
+
+export default Connection;

package/src/connection/server-capabilities.js

@@ -1,59 +1,60 @@
-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
-};
+import ID_STRATEGY from '#src/constants/id-strategy.js';
+import {assert_condition} from '#src/utils/assert.js';
+import {is_function} from '#src/utils/value.js';
+
+const MIN_POSTGRES_NATIVE_UUIDV7_VERSION_NUM = 180000;
+
+async function scan_server_capabilities(pool_instance) {
+	assert_condition(pool_instance && is_function(pool_instance.query), '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 !== ID_STRATEGY.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

@@ -1,20 +1,33 @@
-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
-	}
-};
-
+import ID_STRATEGY from '#src/constants/id-strategy.js';
+
+// TODO: add `model_options.timestamps` as a real config flag and wire its behavior
+// through model lifecycle defaults, docs, and update/insert timestamp handling.
+const DEFAULT_SLUG = 'data';
+
+const defaults = {
+	connection_options: {
+		max: 10,
+		debug: false
+	},
+
+	schema_options: {
+		id_strategy: ID_STRATEGY.uuidv7,
+		auto_index: true,
+
+		default_slug: DEFAULT_SLUG,
+		slugs: [],
+		/*
+		timestamps: true,
+		*/
+	},
+
+	model_options: {
+		table_name: null,
+
+		// TODO: we'll deal with data_column later
+		data_column: DEFAULT_SLUG,
+
+	}
+};
+
 export default defaults;

package/src/constants/{id-strategies.js → id-strategy.js}

@@ -1,29 +1,28 @@
-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;
+import {assert_condition} from '#src/utils/assert.js';
+
+const ID_STRATEGY = Object.freeze({
+	bigserial: 'bigserial',
+	uuidv7: 'uuidv7'
+});
+
+const id_strategy_values = Object.freeze(Object.values(ID_STRATEGY));
+
+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(', ');
+}
+
+function assert_id_strategy(id_strategy) {
+	assert_condition(is_valid(id_strategy), id_strategy_error());
+}
+
+export {
+	ID_STRATEGY,
+	is_valid,
+	assert_id_strategy
+};
+
+export default ID_STRATEGY;

package/src/constants/intake-mode.js

@@ -0,0 +1,8 @@
+const INTAKE_MODE = Object.freeze({
+	from: 'from',
+	hydrate: 'hydrate'
+});
+
+export {INTAKE_MODE};
+
+export default INTAKE_MODE;

package/src/debug/debug-logger.js

@@ -1,15 +1,17 @@
-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));
-}
+import safe_json_stringify from '#src/utils/json-safe.js';
+
+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));
+}
+
+export default debug_logger;

package/src/errors/model-overwrite-error.js

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

package/src/errors/query-error.js

@@ -1,23 +1,25 @@
-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
-		}
-	};
-};
+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
+		}
+	};
+};
+
+export default QueryError;

package/src/errors/validation-error.js

@@ -1,23 +1,25 @@
-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
-		}
-	};
-};
+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
+		}
+	};
+};
+
+export default ValidationError;