jsonbadger 0.5.0 → 0.6.0

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

@@ -0,0 +1,9 @@
+import {register, resolve} from '#src/field-types/registry.js';
+
+const field_type = Object.freeze({
+	register,
+	resolve
+});
+
+export default field_type;
+export {field_type};

package/src/field-types/registry.js

@@ -1,122 +1,149 @@
-/*
-Assumptions and trade-offs:
-- A process-level default registry is used for built-ins and extension registration.
-- Type resolution is explicit; unsupported references throw immediately.
-*/
-import {get_foundational_field_types} from '#src/field-types/builtins/index.js';
-
-function FieldTypeRegistry() {
-	this.type_constructors_by_name = Object.create(null);
-	this.type_name_by_reference = new Map();
-	this.register_foundational_types();
-}
-
-FieldTypeRegistry.prototype.register_foundational_types = function () {
-	const foundational_type_entries = get_foundational_type_entries();
-	let entry_index = 0;
-
-	while(entry_index < foundational_type_entries.length) {
-		const type_entry = foundational_type_entries[entry_index];
-		const type_name = type_entry[0];
-		const type_definition = type_entry[1];
-
-		this.register_field_type(type_name, type_definition.constructor, type_definition.references);
-		entry_index += 1;
-	}
-};
-
-FieldTypeRegistry.prototype.register_field_type = function (type_name, type_constructor, references) {
-	const resolved_name = resolve_type_name_value(type_name);
-	const resolved_references = resolve_reference_list(references);
-
-	this.type_constructors_by_name[resolved_name] = type_constructor;
-	this.type_name_by_reference.set(resolved_name, resolved_name);
-	register_reference_aliases(this.type_name_by_reference, resolved_name, resolved_references);
-};
-
-FieldTypeRegistry.prototype.resolve_field_type_name = function (type_reference) {
-	return resolve_field_type_name_value(
-		this.type_name_by_reference,
-		this.type_constructors_by_name,
-		type_reference
-	);
-};
-
-FieldTypeRegistry.prototype.has_field_type = function (type_reference) {
-	const type_name = this.resolve_field_type_name(type_reference);
-	return type_name !== null;
-};
-
-FieldTypeRegistry.prototype.create_field_type = function (path_value, type_reference, options) {
-	const type_name = this.resolve_field_type_name(type_reference);
-	assert_supported_type_name(path_value, type_name);
-
-	const type_constructor = this.type_constructors_by_name[type_name];
-	const field_options = create_field_options(options);
-
-	return new type_constructor(path_value, field_options, this);
-};
-
-function get_foundational_type_entries() {
-	const foundational_types = get_foundational_field_types();
-	return Object.entries(foundational_types);
-}
-
-function resolve_type_name_value(type_name) {
-	return String(type_name);
-}
-
-function resolve_reference_list(references) {
-	if(Array.isArray(references)) {
-		return references;
-	}
-
-	return [];
-}
-
-function register_reference_aliases(type_name_by_reference, resolved_name, resolved_references) {
-	let reference_index = 0;
-
-	while(reference_index < resolved_references.length) {
-		type_name_by_reference.set(resolved_references[reference_index], resolved_name);
-		reference_index += 1;
-	}
-}
-
-function resolve_field_type_name_value(type_name_by_reference, type_constructors_by_name, type_reference) {
-	if(type_name_by_reference.has(type_reference)) {
-		return type_name_by_reference.get(type_reference);
-	}
-
-	if(typeof type_reference === 'string' && type_constructors_by_name[type_reference]) {
-		return type_reference;
-	}
-
-	return null;
-}
-
-function create_field_options(options) {
-	return Object.assign({}, options || {});
-}
-
-function assert_supported_type_name(path_value, type_name) {
-	if(!type_name) {
-		throw new Error('Unsupported field type at path "' + path_value + '"');
-	}
-}
-
-const default_field_type_registry = new FieldTypeRegistry();
-
-function register_field_type(type_name, type_constructor, references) {
-	default_field_type_registry.register_field_type(type_name, type_constructor, references);
-}
-
-function resolve_field_type(type_reference) {
-	return default_field_type_registry.resolve_field_type_name(type_reference);
-}
-
-function create_field_type(path_value, type_reference, options) {
-	return default_field_type_registry.create_field_type(path_value, type_reference, options);
-}
-
-export {create_field_type, default_field_type_registry, FieldTypeRegistry, register_field_type, resolve_field_type};
+import {get_foundational_field_types} from '#src/field-types/builtins/index.js';
+import {deep_clone} from '#src/utils/object.js';
+
+function FieldTypeRegistry() {
+	this.type_constructors_by_name = Object.create(null);
+	this.type_name_by_alias = new Map();
+	this.register_foundational_types();
+}
+
+/**
+ * Registers the foundational field-type entries in the default registry format.
+ *
+ * @returns {void}
+ */
+FieldTypeRegistry.prototype.register_foundational_types = function () {
+	const foundational_type_entries = Object.entries(get_foundational_field_types());
+	let entry_index = 0;
+
+	while(entry_index < foundational_type_entries.length) {
+		const type_entry = foundational_type_entries[entry_index];
+		const type_name = type_entry[0];
+		const type_definition = type_entry[1];
+
+		this.register(type_name, type_definition.constructor, type_definition.aliases);
+		entry_index += 1;
+	}
+};
+
+/**
+ * Registers a field type and its lookup aliases.
+ *
+ * @param {string} type_name Canonical field-type name.
+ * @param {Function} type_constructor Field-type constructor.
+ * @param {Array<*>} aliases Optional alias list used for lookup resolution.
+ * @returns {void}
+ */
+FieldTypeRegistry.prototype.register = function (type_name, type_constructor, aliases) {
+	const resolved_name = String(type_name);
+	const resolved_aliases = Array.isArray(aliases) ? aliases : [];
+
+	this.type_constructors_by_name[resolved_name] = type_constructor;
+	this.type_name_by_alias.set(resolved_name, resolved_name);
+
+	register_aliases(this.type_name_by_alias, resolved_name, resolved_aliases);
+};
+
+/**
+ * Resolves an alias or canonical name to the registered field-type name.
+ *
+ * @param {*} type_alias Alias or canonical field-type reference.
+ * @returns {string|null}
+ */
+FieldTypeRegistry.prototype.resolve = function (type_alias) {
+	if(this.type_name_by_alias.has(type_alias)) {
+		return this.type_name_by_alias.get(type_alias);
+	}
+
+	if(typeof type_alias === 'string' && this.type_constructors_by_name[type_alias]) {
+		return type_alias;
+	}
+
+	return null;
+};
+
+/**
+ * Checks whether a field type exists in the registry.
+ *
+ * @param {*} type_alias Alias or canonical field-type reference.
+ * @returns {boolean}
+ */
+FieldTypeRegistry.prototype.has_field_type = function (type_alias) {
+	const type_name = this.resolve(type_alias);
+	return type_name !== null;
+};
+
+/**
+ * Creates a field-type instance for a schema path.
+ *
+ * @param {string} path_value Schema path.
+ * @param {*} type_alias Alias or canonical field-type reference.
+ * @param {object} options Field options.
+ * @returns {object}
+ * @throws {Error} When the field type is unsupported.
+ */
+FieldTypeRegistry.prototype.create = function (path_value, type_alias, options) {
+	const type_name = this.resolve(type_alias);
+
+	if(!type_name) {
+		throw new Error('Unsupported field type at path "' + path_value + '"');
+	}
+
+	const type_constructor = this.type_constructors_by_name[type_name];
+	const field_options = create_field_options(options);
+
+	return new type_constructor(path_value, field_options, this);
+};
+
+/**
+ * Stores aliases in the lookup map for a canonical field-type name.
+ *
+ * @param {Map<*, string>} type_name_by_alias Alias-to-name lookup map.
+ * @param {string} resolved_name Canonical field-type name.
+ * @param {Array<*>} resolved_aliases Normalized alias list.
+ * @returns {void}
+ */
+function register_aliases(type_name_by_alias, resolved_name, resolved_aliases) {
+	let alias_index = 0;
+
+	// Resolve aliases once at registration time so later lookups stay canonical.
+	while(alias_index < resolved_aliases.length) {
+		type_name_by_alias.set(resolved_aliases[alias_index], resolved_name);
+		alias_index += 1;
+	}
+}
+
+/**
+ * Clones plain field options without flattening live FieldType instances.
+ *
+ * @param {object} options Field options.
+ * @returns {object}
+ */
+function create_field_options(options) {
+	// Bugfix note:
+	// Parser-generated options can include nested FieldType instances (`of_field_type`, `of_field_types`).
+	// Those must keep their prototype methods intact, so the clone helper preserves custom instances by reference.
+	return deep_clone(options || {});
+}
+
+const default_field_type_registry = new FieldTypeRegistry();
+
+function register(type_name, type_constructor, aliases) {
+	default_field_type_registry.register(type_name, type_constructor, aliases);
+}
+
+function resolve(type_alias) {
+	return default_field_type_registry.resolve(type_alias);
+}
+
+function create(path_value, type_alias, options) {
+	return default_field_type_registry.create(path_value, type_alias, options);
+}
+
+export {
+	create,
+	default_field_type_registry,
+	FieldTypeRegistry,
+	register,
+	resolve
+};

package/src/index.js

@@ -1,36 +1,26 @@
-import connect from '#src/connection/connect.js';
-import disconnect from '#src/connection/disconnect.js';
-import IdStrategies from '#src/constants/id-strategies.js';
-import Schema from '#src/schema/schema.js';
-import model from '#src/model/model-factory.js';
-import {create_field_type, register_field_type, resolve_field_type} from '#src/field-types/registry.js';
-import {boolean_convert_to_false, boolean_convert_to_true, uuidv7_type_reference} from '#src/field-types/builtins/index.js';
-
-const jsonbadger = {
-	connect,
-	disconnect,
-	model,
-	create_field_type,
-	register_field_type,
-	resolve_field_type,
-	Schema,
-	IdStrategies,
-	field_types: {
-		UUIDv7: uuidv7_type_reference,
-		boolean_convert_to_true,
-		boolean_convert_to_false
-	}
-};
-
-export {
-	connect,
-	disconnect,
-	model,
-	create_field_type,
-	register_field_type,
-	resolve_field_type,
-	Schema,
-	IdStrategies
-};
-
-export default jsonbadger;
+import connect from '#src/connection/connect.js';
+import ID_STRATEGY from '#src/constants/id-strategy.js';
+import Schema from '#src/schema/schema.js';
+import field_type from '#src/field-types/field-type-namespace.js';
+import {boolean_convert_to_false, boolean_convert_to_true, uuidv7_type_reference} from '#src/field-types/builtins/index.js';
+
+const jsonbadger = {
+	ID_STRATEGY,
+	connect,
+	field_type,
+	Schema,
+	field_types: {
+		UUIDv7: uuidv7_type_reference,
+		boolean_convert_to_true,
+		boolean_convert_to_false
+	}
+};
+
+export {
+	ID_STRATEGY,
+	connect,
+	field_type,
+	Schema
+};
+
+export default jsonbadger;

package/src/migration/ensure-index.js

@@ -1,155 +1,158 @@
-import {assert_condition, assert_identifier, assert_path, quote_identifier} from '#src/utils/assert.js';
-import {build_path_literal, split_dot_path} from '#src/utils/object-path.js';
-import sql_runner from '#src/sql/sql-runner.js';
-import {is_object, is_string} from '#src/utils/value.js';
-
-export default async function ensure_index(table_name, index_spec, data_column, index_options) {
-	assert_identifier(table_name, 'table_name');
-	assert_identifier(data_column, 'data_column');
-
-	const normalized_index_spec = normalize_index_spec(index_spec);
-	const normalized_index_options = normalize_index_options(index_options);
-
-	const table_identifier = quote_identifier(table_name);
-	const data_identifier = quote_identifier(data_column);
-	const index_name = resolve_index_name(table_name, data_column, normalized_index_spec, normalized_index_options);
-	const index_identifier = quote_identifier(index_name);
-
-	if(is_string(normalized_index_spec)) {
-		assert_condition(
-			normalized_index_options.unique !== true,
-			'unique index is not supported for single-path GIN indexes'
-		);
-
-		const expression = build_json_path_expression(data_identifier, normalized_index_spec);
-		const sql_text =
-			'CREATE INDEX IF NOT EXISTS ' + index_identifier +
-			' ON ' + table_identifier + ' USING GIN ((' + expression + '));';
-
-		await sql_runner(sql_text, []);
-		return;
-	}
-
-	const sorted_path_entries = Object.entries(normalized_index_spec);
-	const expression_list = [];
-	let entry_position = 0;
-
-	while(entry_position < sorted_path_entries.length) {
-		const path_entry = sorted_path_entries[entry_position];
-		const path_value = path_entry[0];
-		const direction_value = path_entry[1];
-		const direction_sql = direction_value === -1 ? 'DESC' : 'ASC';
-		const expression = build_text_path_expression(data_identifier, path_value);
-
-		expression_list.push('(' + expression + ') ' + direction_sql);
-		entry_position += 1;
-	}
-
-	const unique_prefix = normalized_index_options.unique ? 'UNIQUE ' : '';
-	const sql_text =
-		'CREATE ' + unique_prefix + 'INDEX IF NOT EXISTS ' + index_identifier +
-		' ON ' + table_identifier + ' (' + expression_list.join(', ') + ');';
-
-	await sql_runner(sql_text, []);
-}
-
-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_index_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_index_spec[path_value] = direction_value;
-		entry_position += 1;
-	}
-
-	return normalized_index_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 resolve_index_name(table_name, data_column, index_spec, index_options) {
-	if(index_options.name) {
-		return index_options.name;
-	}
-
-	if(is_string(index_spec)) {
-		const path_suffix = index_spec.replace(/\./g, '_');
-		return build_index_name(table_name, data_column, path_suffix + '_gin');
-	}
-
-	const index_entries = Object.entries(index_spec);
-	const path_suffix_parts = [];
-	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];
-		const direction_suffix = direction_value === -1 ? 'desc' : 'asc';
-		path_suffix_parts.push(path_value.replace(/\./g, '_') + '_' + direction_suffix);
-		entry_position += 1;
-	}
-
-	return build_index_name(table_name, data_column, path_suffix_parts.join('_') + '_btree');
-}
-
-function build_json_path_expression(data_identifier, path_value) {
-	const path_segments = split_dot_path(path_value);
-
-	if(path_segments.length === 1) {
-		return data_identifier + " -> '" + path_segments[0] + "'";
-	}
-
-	return data_identifier + " #> '" + build_path_literal(path_segments) + "'";
-}
-
-function build_text_path_expression(data_identifier, path_value) {
-	const path_segments = split_dot_path(path_value);
-
-	if(path_segments.length === 1) {
-		return data_identifier + " ->> '" + path_segments[0] + "'";
-	}
-
-	return data_identifier + " #>> '" + build_path_literal(path_segments) + "'";
-}
-
-function build_index_name(table_name, data_column, path_suffix) {
-	const raw_name = 'idx_' + table_name + '_' + data_column + '_' + path_suffix;
-	const normalized_name = raw_name.toLowerCase().replace(/[^a-z0-9_]/g, '_');
-	return normalized_name.slice(0, 63);
+/*
+ * MODULE RESPONSIBILITY
+ * Ensure the declared model indexes exist in the backing database.
+ */
+import {assert_condition, assert_identifier, assert_path, quote_identifier} from '#src/utils/assert.js';
+import {build_path_literal, split_dot_path} from '#src/utils/object-path.js';
+import {is_object, is_string} from '#src/utils/value.js';
+import run from '#src/sql/run.js';
+
+async function ensure_index(context) {
+	const {
+		table_name,
+		index_definition,
+		data_column,
+		connection
+	} = context;
+
+	assert_identifier(table_name, 'table_name');
+	assert_identifier(data_column, 'data_column');
+	assert_sql_safe_index_definition(index_definition);
+
+	const table_identifier = quote_identifier(table_name);
+	const data_identifier = quote_identifier(data_column);
+	const index_name = resolve_index_name(table_name, data_column, index_definition);
+	const index_identifier = quote_identifier(index_name);
+
+	if(index_definition.using === 'gin') {
+		const expression = build_json_path_expression(data_identifier, index_definition.path);
+		const sql_text =
+			`CREATE INDEX IF NOT EXISTS ${index_identifier} ` +
+			`ON ${table_identifier} USING GIN ((${expression}));`;
+
+		await run(sql_text, [], connection);
+		return;
+	}
+
+	const btree_path_order_map = build_btree_path_order_map(index_definition);
+	const sorted_path_entries = Object.entries(btree_path_order_map);
+	const expression_list = [];
+	let entry_position = 0;
+
+	while(entry_position < sorted_path_entries.length) {
+		const path_entry = sorted_path_entries[entry_position];
+		const path_value = path_entry[0];
+		const order_value = path_entry[1];
+		const order_sql = order_value === -1 ? 'DESC' : 'ASC';
+		const expression = build_text_path_expression(data_identifier, path_value);
+
+		expression_list.push('(' + expression + ') ' + order_sql);
+		entry_position += 1;
+	}
+
+	const unique_prefix = index_definition.unique ? 'UNIQUE ' : '';
+	const sql_text =
+		`CREATE ${unique_prefix}INDEX IF NOT EXISTS ${index_identifier} ` +
+		`ON ${table_identifier} (${expression_list.join(', ')});`;
+
+	await run(sql_text, [], connection);
 }
+
+function assert_sql_safe_index_definition(index_definition) {
+	assert_condition(is_object(index_definition), 'index_definition must be an object');
+	assert_condition(index_definition.using === 'gin' || index_definition.using === 'btree', 'index_definition.using must be "gin" or "btree"');
+
+	if(index_definition.name !== undefined) {
+		assert_identifier(index_definition.name, 'index_definition.name');
+	}
+
+	if(index_definition.using === 'gin') {
+		assert_condition(is_string(index_definition.path), 'index_definition.path must be a string when using is "gin"');
+		assert_path(index_definition.path, 'index path');
+		return;
+	}
+
+	const has_single_path = is_string(index_definition.path);
+	const has_multiple_paths = is_object(index_definition.paths) && Object.keys(index_definition.paths).length > 0;
+
+	assert_condition(has_single_path || has_multiple_paths, 'index_definition.path or index_definition.paths is required when using is "btree"');
+
+	if(has_single_path) {
+		assert_path(index_definition.path, 'index path');
+	}
+
+	if(has_multiple_paths) {
+		for(const path_value of Object.keys(index_definition.paths)) {
+			assert_path(path_value, 'index path');
+		}
+	}
+}
+
+function resolve_index_name(table_name, data_column, index_definition) {
+	if(index_definition.name) {
+		return index_definition.name;
+	}
+
+	if(index_definition.using === 'gin') {
+		const path_suffix = index_definition.path.replace(/\./g, '_');
+		return build_index_name(table_name, data_column, path_suffix + '_gin');
+	}
+
+	const btree_path_order_map = build_btree_path_order_map(index_definition);
+	const index_entries = Object.entries(btree_path_order_map);
+	const path_suffix_parts = [];
+	let entry_position = 0;
+
+	while(entry_position < index_entries.length) {
+		const index_entry = index_entries[entry_position];
+		const path_value = index_entry[0];
+		const order_value = index_entry[1];
+		const order_suffix = order_value === -1 ? 'desc' : 'asc';
+		path_suffix_parts.push(path_value.replace(/\./g, '_') + '_' + order_suffix);
+		entry_position += 1;
+	}
+
+	return build_index_name(table_name, data_column, path_suffix_parts.join('_') + '_btree');
+}
+
+function build_btree_path_order_map(index_definition) {
+	if(is_object(index_definition.paths)) {
+		const path_entries = Object.entries(index_definition.paths);
+
+		if(path_entries.length > 0) {
+			return Object.assign({}, index_definition.paths);
+		}
+	}
+
+	return {
+		[index_definition.path]: index_definition.order
+	};
+}
+
+function build_json_path_expression(data_identifier, path_value) {
+	const path_segments = split_dot_path(path_value);
+
+	if(path_segments.length === 1) {
+		return `${data_identifier} -> '${path_segments[0]}'`;
+	}
+
+	return `${data_identifier} #> '${build_path_literal(path_segments)}'`;
+}
+
+function build_text_path_expression(data_identifier, path_value) {
+	const path_segments = split_dot_path(path_value);
+
+	if(path_segments.length === 1) {
+		return `${data_identifier} ->> '${path_segments[0]}'`;
+	}
+
+	return `${data_identifier} #>> '${build_path_literal(path_segments)}'`;
+}
+
+function build_index_name(table_name, data_column, path_suffix) {
+	const raw_name = `idx_${table_name}_${data_column}_${path_suffix}`;
+	const normalized_name = raw_name.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+	return normalized_name.slice(0, 63);
+}
+
+export default ensure_index;