jsonbadger 0.5.0 → 0.6.0

package/docs/jsonb-ops.md

@@ -0,0 +1,171 @@
+# JSONB Update Pipeline
+
+This document describes the current JSONB update flow.
+
+## Example
+
+This page describes the internal JSONB operator layer after `Model.update_one(...)` input has already been normalized.
+
+```js
+const payload = {
+	$unset: ['profile.address'],
+	$set: {
+		'profile.city': 'Santiago',
+		'profile.tags': ['vip']
+	}
+};
+
+const jsonb_ops = JsonbOps.from(payload, {
+	column_name: '"data"',
+	coalesce: true
+});
+```
+
+> **Note:** `updated_at` is optional in this payload. `Model.prototype.update()` sets it automatically, and direct code paths can pass it explicitly when they want to control the value. The SQL builder only binds the row-level timestamps it receives. A dedicated `model_options.timestamps` flag is a follow-up and is called out by the TODO in `src/constants/defaults.js`.
+
+Runtime flow:
+1. `exec_update_one(...)` splits row-level fields (`created_at`, `updated_at`) from the JSONB payload.
+2. `JsonbOps.from(payload, {column_name, coalesce: true})` returns a `JsonbOps` instance with `target` and ordered `operations`.
+3. `jsonb_ops.compile(parameter_state)` folds `operations` into one SQL RHS expression and binds JSON values into the shared parameter state.
+4. `build_update_query(...)` assembles `UPDATE ... SET ...` and binds only the row-level timestamp parameters it receives after the JSONB expression is finalized.
+5. `exec_update_one(...)` returns the raw updated row to the public model boundary, which can then hydrate or rebase as needed.
+
+> **Note:** `jsonb_set(NULL, ...)` returns `NULL`. Partial JSONB updates must start from `COALESCE(column, '{}'::jsonb)`.
+
+## Current Contract
+
+`JsonbOps.from(...)` accepts the internal operator-style JSONB contract:
+
+```js
+const jsonb_ops = JsonbOps.from(payload, {column_name: '"data"', coalesce: true});
+
+jsonb_ops.target;
+// -> 'COALESCE("data", \'{}\'::jsonb)'
+
+jsonb_ops.operations;
+// -> [
+//   {op: '$replace_roots', value: '{"profile":{"city":"Miami"}}'},
+//   {op: '#-', path: '{"profile","address"}'},
+//   {op: 'jsonb_set', path: '{"profile","tags"}', value: '["vip"]'}
+// ]
+
+const rhs = jsonb_ops.compile(parameter_state);
+```
+
+Rules:
+1. `operations` is ordered for PostgreSQL execution: replace roots -> unsets -> sets.
+2. `from(...)` never receives `parameter_state`.
+3. `compile(...)` is the only JSONB layer that calls `bind_parameter(...)`.
+
+## Update Shapes
+
+The internal JSONB contract is operator-style:
+1. `$replace_roots`: plain object payload replacement.
+2. `$unset`: array of dot paths.
+3. `$set`: map of dot path -> value.
+4. Any top-level non-`$` key is treated as implicit `$set`.
+
+The public `Model.update_one(...)` API is different:
+1. `$set`
+2. `$insert`
+3. `$set_lax`
+4. row-level `updated_at` at the root when provided explicitly
+
+`src/model/operations/update-one.js` is the boundary that adapts the public update API and tracker deltas into the internal JSONB operator contract above.
+
+Tracked document updates come from `DeltaTracker` as:
+
+```js
+{replace_roots: {...}, set: {...}, unset: [...]}
+```
+
+When a model tracks slug roots, tracked paths are prefixed with that slug root. For example, when the default slug is still `data`, tracked paths look like `data.profile.city`. The orchestrator boundary in `src/model/operations/update-one.js` strips the tracked root and maps the delta into operator-style input before calling `JsonbOps.from(...)`.
+
+## Interaction Model
+
+The update path is easiest to reason about as three stages:
+1. change set from `DeltaTracker`,
+2. ordered JSONB operations from `JsonbOps`,
+3. final SQL assembly in the query builder.
+
+### 1. Change Set
+
+Tracked document updates start as pure delta data:
+
+```js
+const tracker_delta = document.$get_delta();
+
+// Example shape:
+// {
+//   replace_roots: {},
+//   set: {
+//     'data.profile.name': 'John Doe',
+//     'data.profile.age': 35
+//   },
+//   unset: ['data.profile.address']
+// }
+```
+
+This shape is still tracker-oriented. It may include the tracked root prefix and it does not use SQL-facing operator names.
+
+### 2. JSONB Operations
+
+The orchestrator adapts the tracker delta into operator-style input and builds one `JsonbOps` instance:
+
+```js
+const jsonb_ops = JsonbOps.from(payload, {
+	column_name: '"data"',
+	coalesce: true
+});
+```
+
+That instance stores:
+1. `target`: the starting SQL expression,
+2. `operations`: the ordered JSONB mutations to apply.
+
+```js
+jsonb_ops.operations;
+// -> [
+//   {op: '#-', path: '{"profile","address"}'},
+//   {op: 'jsonb_set', path: '{"profile","name"}', value: '"John Doe"'},
+//   {op: 'jsonb_set', path: '{"profile","age"}', value: '35'}
+// ]
+```
+
+> **Note:** `JsonbOps.from(...)` does not bind SQL parameters. It only parses and orders JSONB mutations.
+
+### 3. SQL Assembly
+
+The SQL builder compiles those operations against the shared parameter state:
+
+```js
+const compiled_data_expression = jsonb_ops.compile(parameter_state);
+```
+
+That compile step folds the ordered operations into one RHS expression and pushes JSON values into the global parameter list in the same pass.
+
+```js
+// Example result:
+// jsonb_set(
+//   jsonb_set(
+//     COALESCE("data", '{}'::jsonb) #- '{"profile","address"}',
+//     '{"profile","name"}',
+//     $2::jsonb,
+//     true
+//   ),
+//   '{"profile","age"}',
+//   $3::jsonb,
+//   true
+// )
+```
+
+## Module Responsibilities
+
+1. `src/sql/jsonb/ops.js`: parse operator-style JSONB updates and compile them into the RHS SQL expression.
+2. `src/model/operations/update-one.js`: split row timestamps, adapt tracked deltas when needed, and build the query context.
+3. `src/sql/write/build-update-query.js`: compile `jsonb_ops`, then bind row-level timestamps and assemble the final `UPDATE`.
+4. `src/model/model.js`: keep `updated_at` and `created_at` at the row boundary instead of pushing them into JSONB `$set`.
+
+## Pending Note
+
+The current boundary adapter assumes one JSONB slug per document update path. Multi-slug document routing is a follow-up and is called out by the TODO in `src/model/operations/update-one.js`.

package/docs/lifecycle/model-compilation.md

@@ -0,0 +1,111 @@
+# Model Compilation
+
+This note explains what the model factory produces and why JsonBadger creates one concrete `Model` constructor per model definition.
+
+## Quick Example
+
+```js
+const connection = await JsonBadger.connect(uri, options);
+
+const User = connection.model({
+	name: 'User',
+	schema: user_schema,
+	table_name: 'users'
+});
+```
+
+That `User` value is not the shared base `Model`. It is a compiled constructor created for that specific schema, connection, and model configuration.
+
+## Why Compilation Exists
+
+The base `Model` in `src/model/model.js` provides shared behavior such as query helpers, document methods, validation flow, and persistence entry points.
+
+The factory step in `src/model/factory/index.js` turns that shared behavior into a concrete runtime constructor that is bound to one definition. Without that step, the runtime would have nowhere to attach per-model state such as schema metadata, resolved options, and connection ownership.
+
+## Current Flow
+
+```js
+const User = connection.model({
+	name: 'User',
+	schema: user_schema,
+	table_name: 'users'
+});
+```
+
+The current compilation flow is:
+
+1. `Connection.model(...)`
+   1. validates the registration input
+   2. resolves model options such as `table_name`
+   3. delegates compilation to `src/model/factory/index.js`
+2. `model_factory(...)`
+   1. creates a fresh concrete constructor for that definition
+   2. wires inheritance against the base `Model`
+   3. binds schema, options, runtime state, and connection onto the compiled constructor
+3. `Connection.model(...)`
+   1. registers the compiled constructor
+   2. returns it to user code
+
+## What The Factory Produces
+
+The model factory creates a fresh constructor function and then links it to the shared base `Model` chain.
+
+At a high level, the compiled constructor gets:
+
+1. Shared static behavior through `Object.setPrototypeOf(model, Model)`.
+2. Shared instance behavior through `Object.setPrototypeOf(model.prototype, Model.prototype)`.
+3. Definition-specific static state such as:
+   1. `model.schema`
+   2. `model.options`
+   3. `model.state`
+   4. `model.connection`
+4. Definition-specific instance access through `model.prototype.connection`.
+
+This is why each model definition needs its own constructor instance.
+
+## Base Model vs Compiled Model
+
+### Base `Model`
+
+The base `Model` is the shared behavior template.
+
+It defines the common runtime surface used by all compiled models, including:
+
+1. document construction
+2. instance reads and writes
+3. validation flow
+4. `save`, `insert`, `update`, and `delete` entry points
+5. static query and migration helpers
+
+### Compiled Model
+
+A compiled model is the concrete constructor returned by `connection.model(...)`.
+
+It carries the definition-specific runtime context needed for real work:
+
+1. one schema instance
+2. one resolved model-options object
+3. one owning connection
+4. one model-level runtime state bucket
+
+## Why A Detached Constructor Helper Is Not Enough
+
+The important architectural point is not just "create a constructor." The important point is where that happens.
+
+Model construction belongs inside the compiler/factory step because that is the place where JsonBadger already has the full definition context:
+
+1. schema
+2. resolved model options
+3. owning connection
+
+That keeps the lifecycle cohesive. A detached helper that only returns a constructor would still need the compiler step to finish wiring the actual runtime state, so it would split one responsibility across two places without simplifying the design.
+
+## Mental Model
+
+Use this distinction when reading the codebase:
+
+1. `src/model/model.js` defines the shared model behavior.
+2. `src/model/factory/index.js` compiles one concrete model constructor.
+3. `src/connection/connection.js` owns registration and returns compiled models to user code.
+
+So when application code holds `User`, `Post`, or `Invoice`, it is holding a compiled model constructor, not the shared base `Model` itself.

package/docs/lifecycle.md

@@ -0,0 +1,146 @@
+# JsonBadger Document Lifecycle
+
+This page explains what happens to a document instance from construction to persistence and hydration.
+
+Use this page when you need to answer:
+- when `is_new` changes
+- when base fields are populated
+- how `from(...)` and `hydrate(...)` differ
+- what `get(...)`, `set(...)`, and direct `document` mutation actually do
+
+## Lifecycle Overview
+
+```js
+const doc = User.from({
+	name: 'john'
+});
+
+doc.set('data.profile.city', 'Miami');
+await doc.save();
+
+const found = await User.find_one({id: doc.id}).exec();
+const snapshot = found.document;
+```
+
+> **Note:** Query builders are not thenables. Run them with `.exec()`.
+
+Phases:
+- `constructed`: `Model.from(...)`
+- `hydrated`: `Model.hydrate(...)` or document-returning query results
+- `persisted`: successful `doc.save()` on a new document
+- `mutated`: `set(...)` or direct `document` mutation
+
+## Transition Table
+
+| Trigger | From | To | What changes |
+| --- | --- | --- | --- |
+| `Model.from(input)` | none | constructed | builds a new validated document envelope |
+| `Model.hydrate(row)` | none | hydrated | builds a persisted validated document envelope from row-like input |
+| `doc.save()` on new document | constructed | persisted | inserts one row, sets `is_new = false`, and rebases tracked changes |
+| `doc.save()` on existing document | mutated/persisted | persisted | validates current state, updates one row, refreshes `updated_at`, and rebases tracked changes |
+| `find(...).exec()` / `find_one(...).exec()` / `find_by_id(...).exec()` | none | hydrated | row results become hydrated document instances |
+| `update_one(...)` / `delete_one(...)` | none | hydrated | returned row becomes a hydrated document instance, or `null` |
+
+## Constructed
+
+```js
+const doc = User.from({
+	name: 'john',
+	created_at: '2026-03-03T08:00:00.000Z'
+});
+```
+
+At construction time:
+- `doc.is_new === true`
+- base fields are kept at the document root
+- payload values are stored under the schema-owned default slug
+- registered extra slugs stay as sibling document roots
+
+## Hydrated
+
+```js
+const doc = User.hydrate({
+	id: '7',
+	data: {
+		name: 'john'
+	},
+	created_at: '2026-03-03T08:00:00.000Z',
+	updated_at: '2026-03-03T09:00:00.000Z'
+});
+```
+
+Hydration rules:
+- `doc.is_new === false`
+- the outer object is treated as the persisted row envelope
+- the payload is read from the configured default slug key
+- registered extra slugs are read from sibling roots
+- unregistered extra root slugs are ignored
+- dotted payload keys are not expanded during hydration
+
+## Persisted
+
+Create path:
+
+```js
+const created = await User.from({name: 'john'}).save();
+```
+
+Update path:
+
+```js
+const found = await User.find_one({name: 'john'}).exec();
+
+if(found) {
+	found.set('data.profile.city', 'Orlando');
+	await found.save();
+}
+```
+
+After a successful save:
+- `doc.is_new === false`
+- `doc.id`, `doc.created_at`, and `doc.updated_at` reflect persisted row values
+- tracked changes are rebased
+
+Timestamp behavior:
+- inserts keep caller-provided `created_at`, otherwise fill it
+- inserts always refresh `updated_at`
+- updates keep caller-provided `updated_at`, otherwise refresh it
+- updates do not auto-change `created_at`
+
+## Mutated
+
+```js
+const doc = User.from({
+	name: 'john'
+});
+
+doc.set('data.profile.city', 'Miami');
+doc.document.data.profile.city = 'Orlando';
+
+const pending_delta = doc.document.$get_delta();
+```
+
+Mutation rules:
+- `set(...)` resolves aliases, applies schema setter/cast logic, and writes the exact path
+- direct `doc.document[...]` mutation stays allowed
+- direct mutation bypasses `set(...)` and assignment-time casting
+- later `schema.validate(...)` and persistence still enforce the contract
+
+Base-field write rules:
+- `id` is read-only through `set(...)`
+- `created_at` and `updated_at` only allow top-level assignment through `set(...)`
+- dotted timestamp writes are rejected
+
+## FAQ
+
+### Why is `id` not inside the default slug?
+
+Because `id`, `created_at`, and `updated_at` are row-level base fields, not payload fields.
+
+### Why do I need `.exec()` on `find_one()` and `find_by_id()`?
+
+Because those methods return a query builder, not a promise.
+
+### Why did a direct nested mutation skip casting?
+
+Because direct `doc.document[...]` mutation is the lower-level escape hatch. Use `doc.set(...)` when you want schema-aware setter and cast behavior.

package/docs/query-translation.md

@@ -1,4 +1,4 @@
-# query translation
+# query translation
 
 This project compiles Mongo-like filters into PostgreSQL SQL over JSONB data.
 
@@ -35,9 +35,9 @@ This project compiles Mongo-like filters into PostgreSQL SQL over JSONB data.
 
 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.
+- 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
 
@@ -72,7 +72,7 @@ Update path behavior:
 
 This table is the implementation-facing capability map for currently supported query/update operators over JSONB.
 
-| jsonbadger feature | PostgreSQL operator/function | Notes | Indexability expectation |
+| 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 |
@@ -81,7 +81,7 @@ This table is the implementation-facing capability map for currently supported q
 | `$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 |
+| `$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 |
@@ -91,8 +91,9 @@ This table is the implementation-facing capability map for currently supported q
 | `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.
+Index helper behavior:
+- `schema.create_index({using: 'gin', path: 'profile.city'})` creates a GIN index on the extracted JSONB path expression.
+- `schema.create_index({using: 'btree', path: 'age', order: -1})` creates a BTREE index on extracted text path expressions.
+- `schema.create_index({using: 'btree', paths: {name: 1, age: -1}})` creates compound BTREE indexes.
+- GIN descriptors reject `unique`; BTREE descriptors support `unique`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "jsonbadger",
-	"version": "0.5.0",
+	"version": "0.6.0",
 	"description": "JSONB query/model library for PostgreSQL",
 	"main": "index.js",
 	"type": "module",
@@ -53,6 +53,13 @@
 		"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"
+		"test-coverage": "npm run jest-cli -- --runInBand test/unit --coverage",
+		"test-coverage-watch": "npm run jest-cli -- --watch test/unit --coverage",
+		"bump-major": "npm version major",
+		"bump-minor": "npm version minor",
+		"bump-patch": "npm version patch",
+		"bump-major-local": "npm version major --no-git-tag-version",
+		"bump-minor-local": "npm version minor --no-git-tag-version",
+		"bump-patch-local": "npm version patch --no-git-tag-version"
 	}
-}
+}

package/src/connection/connect.js

@@ -1,25 +1,18 @@
 import {Pool} from 'pg';
 
 import defaults from '#src/constants/defaults.js';
+import Connection from '#src/connection/connection.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';
+import {scan_server_capabilities} from '#src/connection/server-capabilities.js';
+import {is_function, is_string} from '#src/utils/value.js';
 
-export default async function connect(uri, options) {
+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 {debug, ...pool_options} = final_options;
 
 	const pool_instance = new Pool(Object.assign({}, pool_options, {connectionString: uri}));
 	let server_capabilities;
@@ -27,24 +20,24 @@ export default async function connect(uri, options) {
 	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;
 	}
 
+	const connection_instance = new Connection(pool_instance, final_options, server_capabilities);
+
 	debug_logger(debug, 'connection_ready', {
 		max: pool_options.max,
 		server_version: server_capabilities.server_version,
 		supports_uuidv7: server_capabilities.supports_uuidv7
 	});
 
-	return pool_instance;
+	return connection_instance;
 }
 
 async function close_pool_quietly(pool_instance) {
-	if(!pool_instance || typeof pool_instance.end !== 'function') {
+	if(!pool_instance || !is_function(pool_instance.end)) {
 		return;
 	}
 
@@ -54,3 +47,5 @@ async function close_pool_quietly(pool_instance) {
 		// Ignore cleanup failures so the original connection/capability error is preserved.
 	}
 }
+
+export default connect;