jsonbadger 0.6.0 → 0.6.2

package/README.md

@@ -1,6 +1,6 @@
 # JsonBadger
 
-JsonBadger is a Node.js library that simplifies working with complex JSON data in PostgreSQL. Instead of writing raw, complex SQL to query nested `jsonb` columns, JsonBadger lets you define schemas and interact with your data using a clean, object-based API and simple query operators.
+JsonBadger is a Node.js library for working with complex JSON data in PostgreSQL through a schema-driven model API. Instead of building nested JSONB queries by hand, you define schemas and use document-style models, query operators, and persistence helpers.
 
 ## Why did I create this utility?
 
@@ -36,8 +36,7 @@ const db_uri = 'postgresql://user:pass@localhost:5432/dbname';
 const options = {
 	debug: false,
 	max: 10,
-	ssl: false,
-	auto_index: true
+	ssl: false
 };
 const connection = await JsonBadger.connect(db_uri, options);
 
@@ -48,7 +47,8 @@ const user_schema = new JsonBadger.Schema({
 	type: {type: String},
 	email: {type: String, index: {unique: true, name: 'idx_users_email_unique'}}
 }, {
-	id_strategy: JsonBadger.IdStrategies.bigserial
+	id_strategy: JsonBadger.ID_STRATEGY.bigserial,
+	auto_index: true
 });
 
 // 3. Declare indexes on schema (path-level + schema-level compound index)
@@ -59,16 +59,15 @@ user_schema.create_index({using: 'btree', paths: {name: 1, type: -1}});
 const User = connection.model({
 	name: 'User',
 	schema: user_schema,
-	table_name: 'users',
-	auto_index: false // optional model-level override
+	table_name: 'users'
 });
 
-// 5. Run migrations manually (optional if you rely on first-write auto table creation via save()/update_one())
+// 5. Run migrations manually
 await User.ensure_table();
-await User.ensure_index();
+await User.ensure_indexes();
 
 // 6. Save a document
-const saved_user = await new User({
+const saved_user = await User.from({
 	name: 'john',
 	age: 30,
 	type: 'admin'
@@ -84,7 +83,7 @@ const found_user = await User.find_one({
 // found_user?.to_json() -> { id, name, age, type, created_at, updated_at }
 ```
 
-When using `IdStrategies.uuidv7`, declare it on the schema. JsonBadger checks PostgreSQL native `uuidv7()` support automatically during `Model.ensure_table()` using capability data captured at `connect(...)`. You do not need to run manual version checks; `SELECT version();` and `SHOW server_version;` are optional troubleshooting commands only.
+When using `ID_STRATEGY.uuidv7`, declare it on the schema. JsonBadger checks support automatically during `Model.ensure_table()` using capability data captured at `connect(...)`.
 
 ## Examples Cheat Sheet
 
@@ -96,15 +95,15 @@ For the document state flow from `new Model(...)` through `save()`, hydration, d
 
 * **JSONB-first**: Model API designed specifically for PostgreSQL JSONB.
 * **Validation**: FieldType-based schema validation built in.
-* **Querying**: Mongo-style query operators (e.g., `$gt`, `$regex`) compiled into SQL.
+* **Querying**: Mongo-style query operators such as `$gt`, `$regex`, `$contains`, and `$elem_match`.
 * **Runtime document APIs**: `get`, `set`, alias virtuals, serialization helpers, `mark_modified`/dirty tracking, and immutable enforcement after save.
-* **JSON update operators**: PostgreSQL-native `jsonb_set`, `jsonb_insert`, and `jsonb_set_lax` support in `update_one(...)`.
-* **Migrations**: Helpers for `ensure_table` and `ensure_index`.
-* **Configurable row IDs**: use `IdStrategies.bigserial` and `IdStrategies.uuidv7` (`uuidv7` is generated by PostgreSQL via native `uuidv7()` support).
+* **JSON updates**: `update_one(...)` supports implicit keys, `$set`, `$unset`, and `$replace_roots`.
+* **Migrations**: Helpers for `ensure_table`, `ensure_indexes`, and `ensure_model`.
+* **Configurable row IDs**: use `ID_STRATEGY.bigserial` and `ID_STRATEGY.uuidv7`.
 * **ID create semantics**: for `uuidv7`, caller-provided `id` is used on create when present; otherwise PostgreSQL generates it. For `bigserial`, create ignores caller-provided `id` and PostgreSQL generates it.
 * **Timestamp helper semantics**: `created_at` and `updated_at` are helper fields. Create keeps caller values when provided, otherwise auto-fills both. Updates keep caller `updated_at` when provided, otherwise auto-refresh `updated_at`.
-* **Configurable index lifecycle**: `auto_index` can be set at connection and overridden per model.
-* **UUIDv7 compatibility gating**: JsonBadger checks support automatically and fails early with server version/capability context when unavailable.
+* **Configurable index lifecycle**: `auto_index` is a schema option that controls whether `ensure_model()` also ensures indexes.
+* **UUIDv7 compatibility checks**: JsonBadger checks support automatically and fails early when unavailable.
 * **Document instance returns**: data-returning methods return document instances with top-level base fields (`id`, `created_at`, `updated_at`), and `.to_json()` / `.$serialize()` for plain-object snapshots.
 * **Modern**: Native ESM package.
 
@@ -118,7 +117,7 @@ For the document state flow from `new Model(...)` through `save()`, hydration, d
 * [`docs/api/field-types.md`](docs/api/field-types.md)
 * [`docs/examples.md`](docs/examples.md) (complete example cheat sheet for queries, updates, and runtime document methods)
 * [`docs/lifecycle.md`](docs/lifecycle.md) (document phases, hydration/save flow, dirty tracking, and serialization)
-* [`docs/query-translation.md`](docs/query-translation.md) (includes PostgreSQL capability map for query/update operators and indexability expectations)
+* [`docs/advanced/query-translation.md`](docs/advanced/query-translation.md) (advanced PostgreSQL reference for operators and query behavior)
 * [`docs/local-integration-testing.md`](docs/local-integration-testing.md)
 * [`CHANGELOG.md`](CHANGELOG.md) for release notes and version history
 

package/docs/{architecture-flow.md → advanced/architecture-flow.md}

@@ -1,6 +1,6 @@
 # Architecture Flow
 
-This page shows the current JsonBadger runtime flow as ASCII diagrams.
+Use this page for architecture review and contributor work. If you only want to use the library, start with [`../examples.md`](../examples.md).
 
 ## 1. Bootstrap
 

package/docs/{jsonb-ops.md → advanced/jsonb-ops.md}

@@ -1,10 +1,12 @@
 # JSONB Update Pipeline
 
-This document describes the current JSONB update flow.
+This page is a maintainer reference for the JSONB update flow.
+
+If you only want to use `update_one(...)`, use [`../examples.md`](../examples.md) instead.
 
 ## Example
 
-This page describes the internal JSONB operator layer after `Model.update_one(...)` input has already been normalized.
+This page describes the lower-level JSONB operator layer after `Model.update_one(...)` input has already been normalized.
 
 ```js
 const payload = {

package/docs/{query-translation.md → advanced/query-translation.md}

@@ -1,6 +1,8 @@
 # query translation
 
-This project compiles Mongo-like filters into PostgreSQL SQL over JSONB data.
+Advanced reference for people who want to understand how JsonBadger queries relate to PostgreSQL JSONB features.
+
+If you only want to use the library, start with [`../examples.md`](../examples.md) and [`../api/query-builder.md`](../api/query-builder.md).
 
 ## base behavior
 
@@ -44,17 +46,18 @@ Top-level semantics note:
 - `$json_path_exists` -> `@?` with a `::jsonpath` parameter
 - `$json_path_match` -> `@@` with a `::jsonpath` parameter
 - invalid/empty JSONPath values fail before SQL execution
+- these operators require native PostgreSQL JSONPath support
 
 ## JSON update operators
 
 - `$set` -> `jsonb_set(target, path, value, true)`
-- `$insert` -> `jsonb_insert(target, path, value, insert_after)`
-- `$set_lax` -> `jsonb_set_lax(target, path, value, create_if_missing, null_value_treatment)`
+- `$unset` -> `target #- path`
+- `$replace_roots` -> replace the full JSONB target
+- implicit top-level keys are normalized into `$set`
 
 Update path behavior:
 - Dot paths are validated before SQL execution.
-- Nested numeric segments are allowed for JSON array index paths in updates (for example `tags.0`).
-- Conflicting update paths in a single `update_one(...)` call (same path or parent/child overlap) fail before SQL execution.
+- Tracker-delta shapes (`replace_roots`, `set`, `unset`) are normalized into operator-style buckets before SQL generation.
 
 ## regex
 
@@ -70,7 +73,7 @@ Update path behavior:
 
 ## PostgreSQL capability map
 
-This table is the implementation-facing capability map for currently supported query/update operators over JSONB.
+This table is an advanced PostgreSQL reference for the currently supported query and update operators.
 
 | JsonBadger feature | PostgreSQL operator/function | Notes | Indexability expectation |
 | --- | --- | --- | --- |
@@ -85,11 +88,11 @@ This table is the implementation-facing capability map for currently supported q
 | `$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 |
-| `$json_path_exists` | `@?` | JSONPath existence predicate | Can benefit from JSONB GIN indexing depending on operator class/query shape |
-| `$json_path_match` | `@@` | JSONPath predicate match | Can benefit from JSONB GIN indexing depending on operator class/query shape |
+| `$json_path_exists` | `@?` | JSONPath existence predicate; requires native PostgreSQL JSONPath support | Can benefit from JSONB GIN indexing depending on operator class/query shape |
+| `$json_path_match` | `@@` | JSONPath predicate match; requires native PostgreSQL JSONPath support | Can benefit from JSONB GIN indexing depending on operator class/query shape |
 | `update_one.$set` | `jsonb_set(...)` | Creates missing path segments when configured (`true`) | N/A (write-path function) |
-| `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) |
+| `update_one.$unset` | `#-` | Removes one JSON path from the target | N/A (write-path function) |
+| `update_one.$replace_roots` | direct JSONB replacement | Replaces the full JSONB root before later operations | N/A (write-path function) |
 
 Index helper behavior:
 - `schema.create_index({using: 'gin', path: 'profile.city'})` creates a GIN index on the extracted JSONB path expression.

package/docs/api/connection.md

@@ -22,7 +22,6 @@ const connection = await JsonBadger.connect(uri, options);
 
 - `max`: pool size
 - `debug`: logs SQL/debug events when `true`
-- `auto_index`: server-wide default for automatic index creation when `Model.ensure_table()` is called
 - any supported `pg` pool options (`ssl`, `host`, `port`, `user`, `password`, `database`)
 
 ## Connection Lifecycle
@@ -39,7 +38,7 @@ await connection.disconnect();
 - `connect(...)` performs a PostgreSQL capability scan and caches the result
 - later schema-level `uuidv7` selections are checked against the cached capability info during `Model.ensure_table()`
 
-> **Note:** Troubleshooting SQL like `SELECT version();` and `SHOW server_version;` is optional. Runtime checks are machine-readable and internal.
+> **Note:** You do not need to run manual version checks during normal usage. JsonBadger performs the compatibility checks it needs automatically.
 
 ## Connection Reuse Pattern
 

package/docs/api/document.md

@@ -4,7 +4,7 @@
 
 Most app code should go through `Model.from(...)`, `Model.hydrate(...)`, and model instance methods such as `doc.get(...)`, `doc.set(...)`, and `doc.save()`.
 
-Use `Document` directly when you are working on runtime internals, custom persistence flows, or when you need to adopt trusted state through `doc.rebase(...)`.
+Use `Document` directly only for advanced or framework-level code, such as custom persistence flows or adopting trusted state through `doc.rebase(...)`.
 
 ## TOC
 

package/docs/api/field-types.md

@@ -249,7 +249,7 @@ const schema = new Schema({
 
 ## Introspection
 
-Use `schema.get_path(path_name)` to inspect one compiled field type:
+Use `schema.get_path(path_name)` to inspect one resolved field type:
 
 ```js
 const schema = new Schema({

package/docs/api/index.md

@@ -32,4 +32,4 @@ Default export (`JsonBadger`) includes the same plus:
 - [`model.md`](model.md)
 - [`query-builder.md`](query-builder.md)
 - [`field-types.md`](field-types.md)
-- [`../query-translation.md`](../query-translation.md)
+- [`../advanced/query-translation.md`](../advanced/query-translation.md)

package/docs/api/query-builder.md

@@ -47,7 +47,9 @@ Read/query execution:
 - JSONB key existence: `$has_key`, `$has_any_keys`, `$has_all_keys`
 - JSONPath: `$json_path_exists`, `$json_path_match`
 
-See [`../query-translation.md`](../query-translation.md) for PostgreSQL operator/function mapping.
+> **Note:** Use `$json_path_exists` and `$json_path_match` only when your PostgreSQL version supports native JSONPath queries.
+
+See [`../advanced/query-translation.md`](../advanced/query-translation.md) when you want the advanced PostgreSQL reference behind these operators.
 
 ## Base-field Query Rules
 
@@ -67,15 +69,13 @@ Operator matrix:
 
 ## JSON Key Existence
 
-- `$has_key` maps to PostgreSQL `?`
-- `$has_any_keys` maps to PostgreSQL `?|`
-- `$has_all_keys` maps to PostgreSQL `?&`
+- `$has_key` checks whether one key is present
+- `$has_any_keys` checks whether any key from a list is present
+- `$has_all_keys` checks whether all keys from a list are present
 
 When used with a nested field path, JsonBadger extracts that nested JSONB value first, then applies the existence operator to the extracted value.
 
 ## JSONPath
 
-- `$json_path_exists` maps to `@?`
-- `$json_path_match` maps to `@@`
-
-JsonBadger binds the JSONPath string as a `::jsonpath` parameter.
+- `$json_path_exists` checks whether a JSONPath query finds a match
+- `$json_path_match` checks whether a JSONPath predicate matches

package/docs/examples.md

@@ -4,7 +4,7 @@ JsonBadger is a PostgreSQL-backed document mapper for working with JSONB data th
 
 This page is an example-first cheat sheet for users and AI agents. It shows copy-pasteable JsonBadger usage in increasing complexity and covers the currently implemented query and update operator surface.
 
-Use this page for syntax and working shapes. Use [`docs/api/index.md`](api/index.md) for the module API map and [`docs/query-translation.md`](query-translation.md) for PostgreSQL operator/function semantics.
+Use this page for syntax and working shapes. Use [`docs/api/index.md`](api/index.md) for the module API map and [`docs/advanced/query-translation.md`](advanced/query-translation.md) only when you want the advanced PostgreSQL reference behind the query surface.
 Use [`docs/lifecycle.md`](lifecycle.md) when you need the document phase map instead of operator syntax.
 
 ## How to Read This Page
@@ -69,10 +69,10 @@ When a snippet uses a different value (for example `name: 'jane'`), either seed
 - Query/sort support for base fields is top-level only (no dotted base-field paths like `created_at.value`).
 
 `id` behavior:
-- Create with `IdStrategies.uuidv7`:
+- Create with `ID_STRATEGY.uuidv7`:
   - caller-provided `id` is used.
   - if `id` is omitted, PostgreSQL default `uuidv7()` generates it.
-- Create with `IdStrategies.bigserial`:
+- Create with `ID_STRATEGY.bigserial`:
   - caller-provided `id` is ignored silently.
   - PostgreSQL sequence generates it.
 - Update paths cannot mutate `id`.
@@ -88,7 +88,7 @@ Timestamp helper behavior:
 
 ## Setup and Connect
 
-> Important: `IdStrategies.uuidv7` requires native PostgreSQL `uuidv7()` support (PostgreSQL 18+).
+> Important: `ID_STRATEGY.uuidv7` requires native PostgreSQL `uuidv7()` support (PostgreSQL 18+).
 
 ```js
 import JsonBadger from 'jsonbadger';
@@ -97,27 +97,27 @@ const db_uri = 'postgresql://user:pass@localhost:5432/dbname';
 const options = {
 	debug: false,
 	max: 10,
-	ssl: false,
-	auto_index: true,
-	id_strategy: JsonBadger.IdStrategies.bigserial
+	ssl: false
 };
 
 const connection = await JsonBadger.connect(db_uri, options);
 ```
 
-UUIDv7 server default (PostgreSQL 18+ native `uuidv7()` required):
+Schema-level UUIDv7 selection (PostgreSQL 18+ native `uuidv7()` required):
 
 ```js
 const db_uri = 'postgresql://user:pass@localhost:5432/dbname';
-const options = {
-	id_strategy: JsonBadger.IdStrategies.uuidv7
-};
+const connection = await JsonBadger.connect(db_uri);
 
-const connection = await JsonBadger.connect(db_uri, options);
+const event_schema = new JsonBadger.Schema({
+	name: String
+}, {
+	id_strategy: JsonBadger.ID_STRATEGY.uuidv7
+});
 ```
 
 Notes:
-- JsonBadger checks native `uuidv7()` support automatically during `connect(...)` and caches the capability result.
+- JsonBadger checks native `uuidv7()` support automatically during `Model.ensure_table()` using the capability snapshot captured at `connect(...)`.
 - Run `ensure_table()` / `ensure_indexes()` during startup/bootstrap before normal runtime operations, or use `ensure_model()` when you want the combined path.
 
 Teardown example:
@@ -150,7 +150,7 @@ const AuditLog = connection.model({
 	schema: new JsonBadger.Schema({
 		event_name: String
 	}, {
-		id_strategy: JsonBadger.IdStrategies.uuidv7 // PostgreSQL 18+ native uuidv7() required
+		id_strategy: JsonBadger.ID_STRATEGY.uuidv7 // PostgreSQL 18+ native uuidv7() required
 	}),
 	table_name: 'audit_logs'
 });
@@ -160,15 +160,15 @@ const Counter = connection.model({
 	schema: new JsonBadger.Schema({
 		label: String
 	}, {
-		id_strategy: JsonBadger.IdStrategies.bigserial // schema override
+		id_strategy: JsonBadger.ID_STRATEGY.bigserial // schema override
 	}),
 	table_name: 'counters'
 });
 ```
 
 Notes:
-- `id_strategy` lives on the schema. If omitted, the library default is `bigserial`.
-- `IdStrategies.uuidv7` uses database-generated IDs (`DEFAULT uuidv7()`) and JsonBadger validates support internally.
+- `id_strategy` lives on the schema. If omitted, the library default is `uuidv7`.
+- `ID_STRATEGY.uuidv7` uses database-generated IDs and JsonBadger validates support automatically.
 
 Create-time `id` behavior example:
 
@@ -205,6 +205,8 @@ const user_schema = new JsonBadger.Schema({
 	},
 	orders: [{sku: String, qty: Number, price: Number}],
 	payload: {}
+}, {
+	id_strategy: JsonBadger.ID_STRATEGY.bigserial
 });
 
 // Schema-level indexes (single path and compound)
@@ -215,9 +217,7 @@ const connection = await JsonBadger.connect(db_uri, options);
 const User = connection.model({
 	name: 'User',
 	schema: user_schema,
-	table_name: 'users',
-	auto_index: true,
-	id_strategy: JsonBadger.IdStrategies.bigserial
+	table_name: 'users'
 });
 ```
 
@@ -274,7 +274,7 @@ Quick FieldType reference:
 
 Edge cases and practical notes:
 - In-place changes to nested values under `doc.document[...]` bypass `doc.set(...)`; prefer `doc.set(...)` when you want assignment-time casting and setter logic.
-- Arrays default to `[]`; set `default: undefined` to disable the implicit empty-array default.
+- Arrays default to `null` unless you explicitly declare a default such as `default: []`.
 - For `Map`-like paths, prefer `document.set('handles.github', 'name')` so casting and dirty tracking run.
 
 ## Create and Save Documents
@@ -419,10 +419,10 @@ const UniqueUser = connection.model({
 await UniqueUser.ensure_table();
 await UniqueUser.ensure_indexes();
 
-await new UniqueUser({email: 'john@example.com'}).save();
+await UniqueUser.from({email: 'john@example.com'}).save();
 
 try {
-	await new UniqueUser({email: 'john@example.com'}).save();
+	await UniqueUser.from({email: 'john@example.com'}).save();
 } catch(error) {
 	if(error.name === 'query_error') {
 		const error_payload = error.to_json();
@@ -596,6 +596,8 @@ await User.find({payload: {$has_key: 'profile.city'}}).exec();
 
 `$json_path_exists` (`@?`) and `$json_path_match` (`@@`):
 
+> **Note:** Use these operators only when your PostgreSQL version supports native JSONPath queries.
+
 Assumes:
 - Your seeded `payload` includes shapes like `items[*].qty` and `score` (as shown in `## Create and Save Documents`).
 
@@ -618,7 +620,7 @@ Expected behavior:
 
 ## Update Operators (`update_one`)
 
-`update_one(...)` supports `$set`, `$insert`, and `$set_lax`.
+`update_one(...)` supports `$set`, `$unset`, `$replace_roots`, plus implicit top-level keys that are routed into `$set`.
 
 Assumes (for update and delete sections below):
 - A matching row exists (examples use `name: 'john'` and `name: 'missing'`).
@@ -627,7 +629,7 @@ Assumes (for update and delete sections below):
 Target shape reminder:
 - `tags` is an array, `profile` is an object, and `payload.profile` / `payload.score` are nested JSON values in the seeded row.
 
-Basic `$set` (maps to `jsonb_set(...)`):
+Use `$set` to assign or replace one or more JSON values:
 
 ```js
 const updated_user = await User.update_one(
@@ -645,86 +647,55 @@ const updated_user = await User.update_one(
 Returns: `updated_user` is `User | null`.  
 Snapshot shape: `updated_user?.document` -> `{ id, data, created_at, updated_at }` when the default slug is still `data`.
 
-`$insert` (maps to `jsonb_insert(...)`) with numeric array index paths:
+Use `$unset` to remove one or more JSON paths:
 
 ```js
 await User.update_one({name: 'john'}, {
-	$insert: {
-		'tags.0': 'first_tag'
-	}
-});
-
-await User.update_one({name: 'john'}, {
-	$insert: {
-		'tags.0': {
-			value: 'after_first',
-			insert_after: true
-		}
-	}
+	$unset: [
+		'payload.cleanup_flag',
+		'profile.country'
+	]
 });
 ```
 
-`$set_lax` (maps to `jsonb_set_lax(...)`) object form:
-
-Target shape reminder for `$set_lax`:
-- `payload` is a JSON object; these examples update or delete nested keys inside `payload`.
+`$replace_roots` (replaces the full JSONB document):
 
 ```js
 await User.update_one({name: 'john'}, {
-	$set_lax: {
-		'payload.cleanup_flag': {
-			value: null,
-			null_value_treatment: 'delete_key'
-		}
+	$replace_roots: {
+		name: 'john',
+		age: 31,
+		status: 'active',
+		profile: {city: 'Orlando'}
 	}
 });
 ```
 
-`$set_lax` options example (`create_if_missing`, `null_value_treatment`):
+Implicit top-level keys are routed into `$set`:
 
 ```js
 await User.update_one({name: 'john'}, {
-	$set_lax: {
-		'payload.archived_at': {
-			value: null,
-			create_if_missing: false,
-			null_value_treatment: 'return_target'
-		}
-	}
+	age: 32,
+	'profile.city': 'Tampa'
 });
 ```
 
-Multiple update operators in one call (application order is `$set` -> `$insert` -> `$set_lax`):
+Multiple update operators in one call (application order is `$replace_roots` -> `$unset` -> `$set`):
 
 ```js
 await User.update_one({name: 'john'}, {
-	$set: {
-		'payload.score': 50
-	},
-	$insert: {
-		'tags.0': {value: 'vip', insert_after: true}
+	$replace_roots: {
+		name: 'john',
+		status: 'active',
+		profile: {city: 'Miami'}
 	},
-	$set_lax: {
-		'payload.cleanup_flag': {
-			value: null,
-			null_value_treatment: 'delete_key'
-		}
-	}
-});
-```
-
-Conflict rule (rejected before SQL):
-
-```js
-await User.update_one({name: 'john'}, {
+	$unset: [
+		'profile.country'
+	],
 	$set: {
-		payload: {nested: true}
-	},
-	$set_lax: {
-		'payload.value': 'ok'
+		'payload.score': 50
 	}
 });
-// throws: conflicting update paths (same path or parent/child overlap)
 ```
 
 Timestamp helper examples on update:
@@ -875,7 +846,7 @@ For the full lifecycle contract, see [`docs/lifecycle.md`](lifecycle.md).
 | JSON containment | `$contains` |
 | JSONB key existence | `$has_key`, `$has_any_keys`, `$has_all_keys` |
 | JSONPath | `$json_path_exists`, `$json_path_match` |
-| Updates (`update_one`) | `$set`, `$insert`, `$set_lax` |
+| Updates (`update_one`) | implicit keys, `$set`, `$unset`, `$replace_roots` |
 
 ## Related Docs
 
@@ -885,5 +856,5 @@ For the full lifecycle contract, see [`docs/lifecycle.md`](lifecycle.md).
 - [`docs/api/schema.md`](api/schema.md) (schema API and index declaration rules)
 - [`docs/api/query-builder.md`](api/query-builder.md) (query builder chain and filter families)
 - [`docs/lifecycle.md`](lifecycle.md) (document phases, hydration/save flow, dirty tracking, and serialization)
-- [`docs/query-translation.md`](query-translation.md) (PostgreSQL operator/function mapping)
+- [`docs/advanced/query-translation.md`](advanced/query-translation.md) (advanced PostgreSQL reference)
 - [`docs/local-integration-testing.md`](local-integration-testing.md) (local integration test setup)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "jsonbadger",
-	"version": "0.6.0",
+	"version": "0.6.2",
 	"description": "JSONB query/model library for PostgreSQL",
 	"main": "index.js",
 	"type": "module",