jsonbadger 0.5.0 → 0.6.1

package/src/utils/value.js

@@ -1,30 +1,169 @@
-const is_object = (value) => {
-	return value !== null && typeof value === 'object' && !Array.isArray(value);
-};
-
-const is_not_object = (value) => {
-	return value === null || Array.isArray(value) || typeof value !== 'object';
-};
-
-const is_nan = (value) => {
-	const numeric_value = Number(value);
-	return Number.isNaN(numeric_value);
-};
-
-const is_string = (value) => {
-	return typeof value === 'string';
-};
-
-export {
-	is_object,
-	is_not_object,
-	is_nan,
-	is_string
-};
-
-export default {
-	is_object,
-	is_not_object,
-	is_nan,
-	is_string
-};
+const uuidv7_pattern = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function is_object(value) {
+	return typeof value === 'object'
+		&& !(value == null)
+		&& !(value instanceof Date)
+		&& !(value instanceof Map)
+		&& !(value instanceof Set)
+		&& !Array.isArray(value)
+		&& !ArrayBuffer.isView(value);
+}
+
+function is_not_object(value) {
+	return typeof value !== 'object'
+		|| value == null
+		|| value instanceof Date
+		|| value instanceof Map
+		|| value instanceof Set
+		|| Array.isArray(value)
+		|| ArrayBuffer.isView(value);
+}
+
+/**
+ * Checks whether a value is a plain object with a null or default object prototype.
+ *
+ * @param {*} value Value to inspect.
+ * @returns {boolean}
+ */
+function is_plain_object(value) {
+	if(!is_object(value)) {
+		return false;
+	}
+
+	const prototype_value = Object.getPrototypeOf(value);
+	return prototype_value === Object.prototype || prototype_value === null;
+}
+
+function is_nan(value) {
+	if(value === null || value === undefined) {
+		return true;
+	}
+
+	const numeric_value = Number(value);
+	return Number.isNaN(numeric_value);
+}
+
+/**
+ * Normalizes one value into a finite number, falling back to zero.
+ *
+ * @param {*} value Value to normalize.
+ * @returns {number}
+ */
+function to_number(value) {
+	const number = Number(value || 0);
+	return Number.isFinite(number) ? number : 0;
+}
+
+function to_int(value) {
+	return Math.floor(Number(value));
+}
+
+/**
+ * Checks whether one value is a valid UUIDv7 string.
+ *
+ * @param {*} value Value to inspect.
+ * @returns {boolean}
+ */
+function is_uuid_v7(value) {
+	if(typeof value !== 'string') {
+		return false;
+	}
+
+	return uuidv7_pattern.test(value);
+}
+
+function is_string(value) {
+	return typeof value === 'string';
+}
+
+function is_function(value) {
+	return typeof value === 'function';
+}
+
+function is_boolean(value) {
+	return typeof value === 'boolean';
+}
+
+function is_date(value) {
+	return value instanceof Date;
+}
+
+function is_not_date(value) {
+	return !(value instanceof Date);
+}
+
+function is_valid_timestamp(value) {
+	return !Number.isNaN(new Date(value).getTime());
+}
+
+function to_iso_timestamp(value) {
+	// Treat falsy values as non-normalizable input and return them unchanged
+	// rather than assuming they represent a valid timestamp.
+	if(!value) {
+		return null;
+	}
+
+	if(value instanceof Date) {
+		return value.toISOString();
+	}
+
+	const parsed_timestamp = new Date(value);
+
+	if(Number.isNaN(parsed_timestamp.getTime())) {
+		return String(value);
+	}
+
+	return parsed_timestamp.toISOString();
+}
+
+/**
+ * Returns the value if the evaluator passes, otherwise returns the default.
+ * @param {function} evaluator - The condition to check against.
+ * @param {any} value - The primary value to test.
+ * @param {any} default_value - The fallback value.
+ * @returns {any}
+ */
+function get_if(evaluator, value, default_value) {
+	if(evaluator(value)) {
+		return value;
+	}
+
+	return default_value;
+}
+
+export {
+	is_object,
+	is_plain_object,
+	is_not_object,
+	is_nan,
+	is_uuid_v7,
+	to_int,
+	to_number,
+	is_string,
+	is_function,
+	is_boolean,
+	is_date,
+	is_not_date,
+	is_valid_timestamp,
+	to_iso_timestamp,
+	get_if
+};
+
+export default {
+	is_object,
+	is_plain_object,
+	is_not_object,
+	is_nan,
+	is_uuid_v7,
+	to_int,
+	to_number,
+	is_string,
+	is_function,
+	is_boolean,
+	is_date,
+	is_not_date,
+	is_valid_timestamp,
+	to_iso_timestamp,
+	get_if
+};

package/docs/api.md

@@ -1,152 +0,0 @@
-# jsonbadger API
-
-## Top-level exports
-
-Named exports:
-- `connect(connection_uri, connection_options)`
-- `disconnect()`
-- `Schema`
-- `IdStrategies`
-- `model(schema_instance, model_options)`
-- `create_field_type(path_value, type_reference, options?)`
-- `register_field_type(type_name, type_constructor, references?)`
-- `resolve_field_type(type_reference)`
-
-Default export (`jsonbadger`) includes the same plus:
-- `field_types.UUIDv7`
-- `field_types.boolean_convert_to_true`
-- `field_types.boolean_convert_to_false`
-
-## connect
-
-`connect(connection_uri, connection_options)` opens (or reuses) a shared PostgreSQL pool.
-
-`connection_options`:
-- `max`: pool size (default `10`)
-- `debug`: logs SQL/debug events when `true`
-- `auto_index`: server-wide default for automatic index creation when `Model.ensure_table()` is called (default `true`)
-- `id_strategy`: server-wide default row-id strategy (`IdStrategies.bigserial` or `IdStrategies.uuidv7`, default `IdStrategies.bigserial`)
-- any `pg` pool options (`ssl`, `host`, `port`, `user`, `password`, `database`)
-
-UUIDv7 compatibility behavior:
-- `connect(...)` performs an internal PostgreSQL capability scan (server version + native `uuidv7()` function presence) and caches the result for later model/runtime checks.
-- If the connection-level `id_strategy` resolves to `IdStrategies.uuidv7` and native support is unavailable, `connect(...)` fails fast.
-- Model-level `uuidv7` overrides defined after `connect(...)` are validated on use with the cached capability metadata.
-- Optional troubleshooting commands only: `SELECT version();` and `SHOW server_version;`. Runtime checks use machine-readable checks internally.
-
-## schema
-
-`new Schema(schema_def, options?)`
-
-`Schema` is responsible for document structure and index declarations.
-
-methods:
-- `validate(payload)`
-- `path(path_name)`
-- `get_path_type(path_name)`
-- `is_array_root(path_name)`
-- `create_index(index_spec, index_options?)`
-- `get_indexes()`
-
-`create_index` supports:
-- single-path index: `schema.create_index('profile.city')`
-- compound index: `schema.create_index({name: 1, type: -1})`
-- optional options: `unique` and `name`
-
-Notes:
-- Single-path string specs (`'profile.city'`) create GIN indexes and do not support `unique`.
-- Object specs (`{field: 1}` / compound) create BTREE indexes and support `unique`.
-
-Path-level sugar in schema definitions is also supported:
-- `{name: {type: String, index: true}}` -> single-path index
-- `{age: {type: Number, index: 1}}` -> ascending single-path spec
-- `{age: {type: Number, index: -1}}` -> descending single-path spec
-- `{email: {type: String, index: {unique: true, name: 'idx_users_email_unique'}}}` -> path-level index options
-- optional direction in object form: `direction` or `order` (`1` or `-1`)
-
-## model
-
-`const User = model(user_schema, { table_name, data_column?, id_strategy?, auto_index? })`
-
-- `table_name` is required.
-- `data_column` defaults to `data`.
-- `id_strategy` defaults to connection-level `id_strategy`, then library default `IdStrategies.bigserial`.
-- `auto_index` defaults to model option if set, otherwise connection-level `auto_index`.
-
-UUIDv7 notes:
-- `IdStrategies.uuidv7` uses database-generated row IDs via table DDL (`id UUID PRIMARY KEY DEFAULT uuidv7()`).
-- jsonbadger validates `uuidv7` support before uuidv7-backed table/schema/write paths using cached server capability metadata.
-
-static methods:
-- `ensure_table()`: manual migration call that ensures the table exists (for `IdStrategies.uuidv7`, table DDL uses `DEFAULT uuidv7()`); when `auto_index` is enabled, applies declared schema indexes once per model instance. First-write methods (`save()`, `update_one(...)`) can also create the table automatically.
-- `ensure_index()`: ensures table exists and applies declared schema indexes immediately.
-- `ensure_schema()`: ensures table and applies declared schema indexes.
-- `find(query_filter, projection_value?)`
-- `find_one(query_filter)`
-- `count_documents(query_filter)`
-- `update_one(query_filter, update_definition)`
-  - supported operators: `$set`, `$insert`, `$set_lax`
-  - operator application order is deterministic and nested: `$set` -> `$insert` -> `$set_lax`
-  - `$insert` maps to PostgreSQL `jsonb_insert(...)`
-  - `$set_lax` maps to PostgreSQL `jsonb_set_lax(...)` and supports object form `{ value, create_if_missing?, null_value_treatment? }`
-  - update paths allow numeric nested segments for JSON array indexes (for example, `tags.0`)
-  - conflicting update paths (same path or parent/child overlap across operators) are rejected before SQL execution
-- `delete_one(query_filter)`
-  - deletes one matching row and returns the deleted document data
-  - returns `null` when no row matches
-  - does not implicitly call `ensure_table()`; if the table does not exist yet, returns `null`
-
-instance methods:
-- `validate()`
-- `get(path_name, runtime_options?)`
-- `set(path_name, value, runtime_options?)`
-- `mark_modified(path_name)`
-- `is_modified(path_name?)`
-- `clear_modified()`
-- `to_object(serialization_options?)`
-- `to_json(serialization_options?)`
-- `save()`
-
-Runtime behavior notes:
-- Read/query execution (`find(...).exec()`, `find_one(...).exec()`, `count_documents(...).exec()`) does not implicitly call `ensure_table()`.
-- Use `ensure_table()` / `ensure_schema()` explicitly, or let a first write (`save()` / `update_one(...)`) create the table.
-- `set(...)` applies field setters + casting by default and marks the path as modified.
-- `mark_modified(path_name)` is required after in-place `Mixed`/`Date` mutations (for example mutating nested objects or calling `Date` mutator methods directly).
-- `is_modified(path_name?)` and `clear_modified()` are available runtime helpers for dirty-path inspection/reset.
-- `immutable: true` fields are writable before first persist and become protected after a successful `save()`.
-- `to_object(...)` / `to_json(...)` apply getters by default; pass `{ getters: false }` to bypass getter transforms during serialization.
-
-For built-in FieldType declaration examples and edge-case notes, see [`docs/examples.md`](examples.md).
-
-For copy-paste usage examples (including all current query/update operators), see [`docs/examples.md`](examples.md). For PostgreSQL translation semantics, see [`docs/query-translation.md`](query-translation.md).
-
-## query filters
-
-Supported filter/operator families (current implemented set):
-- scalar comparisons: direct equality, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`
-- sets/arrays: `$in`, `$nin`, `$all`, `$size`, `$contains`, `$elem_match`
-- regex: `$regex` (+ `$options`)
-- JSONB key existence: `$has_key`, `$has_any_keys`, `$has_all_keys`
-- JSONPath: `$json_path_exists`, `$json_path_match`
-
-Existence semantics:
-- `$has_key` / `$has_any_keys` / `$has_all_keys` map directly to PostgreSQL `?`, `?|`, and `?&`.
-- These operators are top-level for the JSONB value on the left side of the operator.
-- When used with a nested field path, jsonbadger extracts that nested JSONB value first, then applies the existence operator to that extracted value.
-
-JSONPath notes:
-- `$json_path_exists` maps to `@?` and binds the JSONPath string as a `::jsonpath` parameter.
-- `$json_path_match` maps to `@@` and binds the JSONPath string as a `::jsonpath` parameter.
-
-## query builder
-
-builder chain:
-- `.where(filter)`
-- `.sort(sort_definition)`
-- `.limit(limit_value)`
-- `.skip(skip_value)`
-- `.exec()`
-
-## PostgreSQL capability map (summary)
-
-See [`docs/query-translation.md`](query-translation.md) for the dedicated operator/function capability map, including update operators (`jsonb_set`, `jsonb_insert`, `jsonb_set_lax`) and indexability expectations for query operators over JSONB.

package/src/connection/disconnect.js

@@ -1,16 +0,0 @@
-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

@@ -1,46 +0,0 @@
-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;
-}