jsonbadger 0.5.0 → 0.6.0

package/docs/examples.md

@@ -1,110 +1,201 @@
-# jsonbadger examples cheat sheet
+# JsonBadger examples cheat sheet
 
-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.
+JsonBadger is a PostgreSQL-backed document mapper for working with JSONB data through a model/document API.
 
-Use this page for syntax and working shapes. Use [`docs/api.md`](api.md) for API reference details and [`docs/query-translation.md`](query-translation.md) for PostgreSQL operator/function semantics.
+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 [`docs/lifecycle.md`](lifecycle.md) when you need the document phase map instead of operator syntax.
 
 ## How to Read This Page
 
 - Examples are ordered from setup -> model usage -> queries -> updates -> runtime behavior.
 - Snippets reuse a `User` model shape where possible.
-- Query operators use the current `$` + `snake_case` naming (for example `$elem_match`, `$has_key`, `$json_path_exists`).
-- This page only includes currently implemented behavior.
-- `Assumes:` notes tell you what earlier setup/data a snippet depends on.
-- Important mechanics: queries run when you call `.exec()` (for example `await User.find({}).exec()`), and direct in-place mutations on nested `doc.data` values may require `doc.mark_modified('path')` after mutating.
-
-Quick jump:
-- [How to Read This Page](#how-to-read-this-page)
-- [Shared Fixture and Assumptions](#shared-fixture-and-assumptions)
-- [Setup and Connect](#setup-and-connect)
-- [ID Strategy Examples](#id-strategy-examples)
-- [Schema and Model Definition](#schema-and-model-definition)
-- [Built-in FieldType Examples](#built-in-fieldtype-examples)
-- [Create and Save Documents](#create-and-save-documents)
-- [Query Basics (find, find_one, count)](#query-basics-find-find_one-count)
-- [Direct Equality and Scalar Comparisons](#direct-equality-and-scalar-comparisons)
-- [Regex Operators](#regex-operators)
-- [Array and JSON Query Operators](#array-and-json-query-operators)
-- [JSONB Key Existence Operators](#jsonb-key-existence-operators)
-- [JSONPath Operators](#jsonpath-operators)
-- [Update Operators (`update_one`)](#update-operators-update_one)
-- [Delete Operations](#delete-operations)
-- [Runtime Document Methods (get/set, dirty tracking, serialization)](#runtime-document-methods-getset-dirty-tracking-serialization)
-- [Optional Alias Path Example](#optional-alias-path-example)
-- [Complete Operator Checklist (Query and Update)](#complete-operator-checklist-query-and-update)
-- [Related Docs](#related-docs)
+- Query operators use the current `$` + `snake_case` naming (for example `$elem_match`, `$has_key`, `$json_path_exists`).
+- This page only includes currently implemented behavior.
+- `Assumes:` notes tell you what earlier setup/data a snippet depends on.
+- Important mechanics: queries run when you call `.exec()` (for example `await User.find({}).exec()`), and direct in-place mutations on `doc.document[...]` bypass `doc.set(...)` and assignment-time casting.
+- Operation scope: this page covers `create`, `save`, `find`, `find_one`, `find_by_id`, `count_documents`, `update_one`, and `delete_one`. Bulk helpers (`insert_many`, `update_many`, `delete_many`) are not part of the current API surface.
+
+Quick jump:
+
+Setup
+- [How to Read This Page](#how-to-read-this-page)
+- [Shared Fixture and Assumptions](#shared-fixture-and-assumptions)
+- [Reserved Base Fields](#reserved-base-fields)
+- [Setup and Connect](#setup-and-connect)
+- [ID Strategy Examples](#id-strategy-examples)
+- [Schema and Model Definition](#schema-and-model-definition)
+- [Built-in FieldType Examples](#built-in-fieldtype-examples)
+- [Create and Save Documents](#create-and-save-documents)
+
+Queries
+- [Query Basics (find, find_one, count_documents)](#query-basics-find-find_one-count_documents)
+- [Direct Equality and Scalar Comparisons](#direct-equality-and-scalar-comparisons)
+- [Regex Operators](#regex-operators)
+- [Array and JSON Query Operators](#array-and-json-query-operators)
+- [JSONB Key Existence Operators](#jsonb-key-existence-operators)
+- [JSONPath Operators](#jsonpath-operators)
+
+Mutations
+- [Update Operators (`update_one`)](#update-operators-update_one)
+- [Delete Operations](#delete-operations)
+
+Advanced
+- [Runtime Document Methods (get/set, dirty tracking, serialization)](#runtime-document-methods-getset-dirty-tracking-serialization)
+- [Lifecycle Quick Reference](#lifecycle-quick-reference)
+- [Optional Alias Path Example](#optional-alias-path-example)
+- [Complete Operator Checklist (Query and Update)](#complete-operator-checklist-query-and-update)
+- [Related Docs](#related-docs)
 
 ## Shared Fixture and Assumptions
 
 Most snippets below are intentionally short and not fully standalone. Unless a section says otherwise, examples assume:
 
-- You already connected with `jsonbadger.connect(...)`.
+- You are running ESM (`import ...`) with top-level `await` enabled.
+- You already connected with `JsonBadger.connect(...)`.
 - You defined the `User` model from `Schema and Model Definition`.
-- You either ran manual migrations (`ensure_table()` / `ensure_schema()`) or allowed a first write to create the table.
+- You already ran startup/bootstrap setup from the migration section below.
 - You seeded at least one `User` document using the `Create and Save Documents` example (including `tags`, `orders`, and `payload`).
 
-When a snippet uses a different value (for example `user_name: 'jane'`), either seed a matching row first or replace the filter value with one that exists in your local data.
+When a snippet uses a different value (for example `name: 'jane'`), either seed a matching row first or replace the filter value with one that exists in your local data.
+
+
+## Reserved Base Fields
+
+- `id`, `created_at`, and `updated_at` are top-level base fields returned in data-returning operations.
+- These base fields exist in schema/runtime introspection even when omitted from user schema input.
+- If user schema declares any of these paths, the user definition is preserved.
+- 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`:
+  - caller-provided `id` is used.
+  - if `id` is omitted, PostgreSQL default `uuidv7()` generates it.
+- Create with `IdStrategies.bigserial`:
+  - caller-provided `id` is ignored silently.
+  - PostgreSQL sequence generates it.
+- Update paths cannot mutate `id`.
 
+Timestamp helper behavior:
+- Create:
+  - provided `created_at` / `updated_at` values are kept.
+  - omitted values are auto-filled.
+- Update:
+  - provided `updated_at` is kept.
+  - omitted `updated_at` is auto-set.
+  - `created_at` is not auto-updated.
 
 ## Setup and Connect
 
+> Important: `IdStrategies.uuidv7` requires native PostgreSQL `uuidv7()` support (PostgreSQL 18+).
+
 ```js
-import jsonbadger from 'jsonbadger';
+import JsonBadger from 'jsonbadger';
 
-await jsonbadger.connect(process.env.APP_POSTGRES_URI, {
+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
-});
+	id_strategy: JsonBadger.IdStrategies.bigserial
+};
+
+const connection = await JsonBadger.connect(db_uri, options);
 ```
 
 UUIDv7 server default (PostgreSQL 18+ native `uuidv7()` required):
 
 ```js
-await jsonbadger.connect(process.env.APP_POSTGRES_URI, {
-	id_strategy: jsonbadger.IdStrategies.uuidv7
-});
+const db_uri = 'postgresql://user:pass@localhost:5432/dbname';
+const options = {
+	id_strategy: JsonBadger.IdStrategies.uuidv7
+};
+
+const connection = await JsonBadger.connect(db_uri, options);
 ```
 
 Notes:
-- jsonbadger checks native `uuidv7()` support automatically during `connect(...)` and caches the capability result.
-- Reads do not auto-create tables. A first write (`save()` / `update_one(...)`) can create the table, or you can call `ensure_table()` / `ensure_schema()` explicitly.
+- JsonBadger checks native `uuidv7()` support automatically during `connect(...)` and caches the capability result.
+- Run `ensure_table()` / `ensure_indexes()` during startup/bootstrap before normal runtime operations, or use `ensure_model()` when you want the combined path.
 
-## ID Strategy Examples
+Teardown example:
 
-Server-wide default (`connect`) plus model override (`model(...)`):
+```js
+await connection.disconnect();
+```
+
+Connection failure pattern (before a pool is established in the process):
 
 ```js
-await jsonbadger.connect(process.env.APP_POSTGRES_URI, {
-	id_strategy: jsonbadger.IdStrategies.uuidv7 // PostgreSQL 18+ native uuidv7() required
-});
+try {
+	await JsonBadger.connect('postgresql://wrong_user:wrong_pass@localhost:5432/dbname');
+} catch(error) {
+	// connection/auth/network failures bubble directly from `pg`
+	console.error(error.message);
+}
+```
+
+## ID Strategy Examples
 
-const AuditLog = jsonbadger.model(new jsonbadger.Schema({
-	event_name: String
-}), {
-	table_name: 'audit_logs',
-	// inherits server id_strategy: uuidv7
+Schema-level `id_strategy` selection:
+
+```js
+const db_uri = 'postgresql://user:pass@localhost:5432/dbname';
+const connection = await JsonBadger.connect(db_uri);
+
+const AuditLog = connection.model({
+	name: 'AuditLog',
+	schema: new JsonBadger.Schema({
+		event_name: String
+	}, {
+		id_strategy: JsonBadger.IdStrategies.uuidv7 // PostgreSQL 18+ native uuidv7() required
+	}),
+	table_name: 'audit_logs'
 });
 
-const Counter = jsonbadger.model(new jsonbadger.Schema({
-	label: String
-}), {
-	table_name: 'counters',
-	id_strategy: jsonbadger.IdStrategies.bigserial // model override
+const Counter = connection.model({
+	name: 'Counter',
+	schema: new JsonBadger.Schema({
+		label: String
+	}, {
+		id_strategy: JsonBadger.IdStrategies.bigserial // schema override
+	}),
+	table_name: 'counters'
 });
 ```
 
 Notes:
-- `id_strategy` precedence is: model option -> connection option -> library default (`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 `bigserial`.
+- `IdStrategies.uuidv7` uses database-generated IDs (`DEFAULT uuidv7()`) and JsonBadger validates support internally.
+
+Create-time `id` behavior example:
+
+```js
+// uuidv7 model: pass-through when provided
+const uuid_user = await AuditLog.create({
+	id: '0194f028-579a-7b5b-8107-b9ad31395f43',
+	event_name: 'login'
+});
+
+// uuidv7 model: DB generates when omitted
+const generated_uuid_user = await AuditLog.create({
+	event_name: 'logout'
+});
+
+// bigserial model: caller id is ignored, DB generates numeric id
+const serial_counter = await Counter.create({
+	id: 999,
+	label: 'requests'
+});
+```
 
 ## Schema and Model Definition
 
 ```js
-const user_schema = new jsonbadger.Schema({
-	user_name: {type: String, required: true, trim: true, index: true, get: (value) => value && value.toUpperCase()},
+const user_schema = new JsonBadger.Schema({
+	name: {type: String, required: true, trim: true, index: true, get: (value) => value && value.toUpperCase()},
 	age: {type: Number, min: 0, index: -1},
 	status: {type: String, immutable: true},
 	tags: [String],
@@ -112,36 +203,40 @@ const user_schema = new jsonbadger.Schema({
 		city: String,
 		country: String
 	},
-	orders: [{sku: String, qty: Number, price: Number}],
-	payload: {}
-});
+	orders: [{sku: String, qty: Number, price: Number}],
+	payload: {}
+});
 
 // Schema-level indexes (single path and compound)
-user_schema.create_index('profile.city');
-user_schema.create_index({user_name: 1, age: -1});
+user_schema.create_index({using: 'gin', path: 'profile.city'});
+user_schema.create_index({using: 'btree', paths: {name: 1, age: -1}});
 
-const User = jsonbadger.model(user_schema, {
+const connection = await JsonBadger.connect(db_uri, options);
+const User = connection.model({
+	name: 'User',
+	schema: user_schema,
 	table_name: 'users',
-	data_column: 'data',
 	auto_index: true,
-	id_strategy: jsonbadger.IdStrategies.bigserial
+	id_strategy: JsonBadger.IdStrategies.bigserial
 });
 ```
 
 Migration helpers (manual/explicit path):
 
 ```js
+// Option A: run table and indexes explicitly
 await User.ensure_table();
-await User.ensure_index();
-// or: ensure_schema() does both (table + declared schema indexes)
-await User.ensure_schema();
+await User.ensure_indexes();
+
+// Option B: run the combined model bootstrap path
+await User.ensure_model();
 ```
 
 ## Built-in FieldType Examples
 
 ```js
-const account_schema = new jsonbadger.Schema({
-	user_name: { type: String, trim: true, required: true },
+const account_schema = new JsonBadger.Schema({
+	name: { type: String, trim: true, required: true },
 	age: { type: Number, min: 0 },
 	is_active: Boolean,
 	joined_at: Date,
@@ -158,22 +253,38 @@ const account_schema = new jsonbadger.Schema({
 });
 ```
 
+Quick FieldType reference:
+
+| Field | FieldType | Example |
+| --- | --- | --- |
+| `name` | `String` | `{ type: String, trim: true, required: true }` |
+| `age` | `Number` | `{ type: Number, min: 0 }` |
+| `is_active` | `Boolean` | `is_active: Boolean` |
+| `joined_at` | `Date` | `joined_at: Date` |
+| `owner_id` | `UUIDv7` | `{ type: 'UUIDv7' }` |
+| `avatar` | `Buffer` | `avatar: Buffer` |
+| `payload` | `Mixed` | `payload: {}` |
+| `tags` | `Array<String>` | `tags: [String]` |
+| `handles` | `Map<String>` | `{ type: Map, of: String }` |
+| `amount` | `Decimal128` | `{ type: 'Decimal128' }` |
+| `visits_64` | `BigInt` | `{ type: 'BigInt' }` |
+| `ratio` | `Double` | `{ type: 'Double' }` |
+| `score_32` | `Int32` | `{ type: 'Int32' }` |
+| `code_or_label` | `Union<String, Number>` | `{ type: 'Union', of: [String, Number] }` |
+
 Edge cases and practical notes:
-- In-place changes to `Mixed` (`{}`) values and `Date` objects do not mark the path dirty automatically; call `doc.mark_modified('path')` after mutating them.
+- 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.
 - For `Map`-like paths, prefer `document.set('handles.github', 'name')` so casting and dirty tracking run.
-- Serialization applies getters by default; use `doc.to_object({ getters: false })` or `doc.to_json({ getters: false })` to bypass them.
 
 ## Create and Save Documents
 
-First write can create the table if it does not exist yet.
-
 Assumes:
 - `User` is defined from the schema/model section above.
 
 ```js
-const user_doc = new User({
-	user_name: 'john',
+const user_doc = User.from({
+	name: 'john',
 	age: 30,
 	status: 'active',
 	tags: ['vip', 'beta'],
@@ -191,47 +302,159 @@ const user_doc = new User({
 	}
 });
 
-await user_doc.validate();
-const saved_user = await user_doc.save();
-// returns: saved data object (plain object); `user_doc.data` is updated to the saved payload
-```
-
-Validation failure pattern (`validation_error`):
-
-```js
-try {
-	const invalid_user = new User({
-		user_name: 'bad_input',
-		age: -1 // violates `min: 0` from the schema example
-	});
-
-	await invalid_user.save();
-} catch(error) {
-	if(error.name === 'validation_error') {
-		const error_payload = error.to_json();
-		// shape: { success: false, error: { type: 'validation_error', message: '...', details: ... } }
-		// `error.details` is the same validation detail payload included in `error_payload.error.details`
-	}
-}
-```
-
-## Query Basics (find, find_one, count)
-
-Assumes (for the query sections below):
-- `User` is defined and at least one document was saved (see `## Create and Save Documents`).
-- Examples that filter by `user_name: 'john'`, `tags`, `orders`, or `payload` assume those fields/values exist in seeded data.
-
-
-```js
-const all_users = await User.find({}).exec();
-// returns: [{ user_name: 'john', ... }, ...] (array of plain data objects)
-
-const found_user = await User.find_one({user_name: 'john'}).exec();
-// returns: { user_name: 'john', ... } or null (plain data object)
-
-const adult_count = await User.count_documents({age: {$gte: 18}}).exec();
-// returns: number
-```
+const saved_user = await user_doc.save();
+```
+
+Returns: `saved_user` is a `User` document instance.  
+Raw document shape: `saved_user.document` -> `{ id, data, created_at, updated_at }` when the default slug is still `data`.  
+Runtime note: read the default slug through `saved_user.document[User.schema.get_default_slug()]`.
+
+Static create and id lookup:
+
+```js
+const created_user = await User.create({
+	name: 'maria',
+	age: 29
+});
+
+const same_user = await User.find_by_id(created_user.id).exec();
+```
+
+Build a new document from external input without marking it persisted:
+
+```js
+const imported_user = User.from({
+	name: '  maria  ',
+	age: '29',
+	created_at: '2026-03-03T08:00:00.000Z'
+});
+```
+
+`User.from(...)` extracts root `id`, `created_at`, and `updated_at` into base fields and treats every other non-base root key as default-slug payload unless that root key is registered in `schema.options.slugs`. It does not interpret payload input as a persisted row envelope.
+
+Set base fields after construction when needed:
+
+```js
+const imported_user = User.from({
+	name: 'maria'
+});
+
+imported_user.id = '7';
+imported_user.created_at = '2026-03-03T08:00:00.000Z';
+imported_user.updated_at = '2026-03-03T09:00:00.000Z';
+```
+
+Hydrate a persisted document from raw row-like data:
+
+```js
+const hydrated_user = User.hydrate({
+	id: '7',
+	data: {
+		name: 'maria',
+		age: '29'
+	},
+	created_at: '2026-03-03T08:00:00.000Z',
+	updated_at: '2026-03-03T09:00:00.000Z'
+});
+```
+
+`User.hydrate(...)` is the row-like path. It reads the payload from the configured default slug key on the outer object and ignores unregistered extra root slugs.
+
+Timestamp helper examples on create:
+
+```js
+// Caller-provided timestamp values are kept
+const user_with_timestamps = await User.create({
+	name: 'timed-user',
+	created_at: '2026-03-03T08:00:00.000Z',
+	updated_at: '2026-03-03T09:00:00.000Z'
+});
+
+// Omitted timestamps are auto-filled
+const user_with_auto_timestamps = await User.create({
+	name: 'auto-timestamp-user'
+});
+```
+
+Validation failure pattern (`validation_error`):
+
+```js
+try {
+	const invalid_user = User.from({
+		name: 'bad_input',
+		age: -1 // violates `min: 0` from the schema example
+	});
+
+	await invalid_user.save();
+} catch(error) {
+	if(error.name === 'validation_error') {
+		const error_payload = error.to_json();
+		// shape: { success: false, error: { type: 'validation_error', message: '...', details: ... } }
+		// `error.details` is the same validation detail payload included in `error_payload.error.details`
+	}
+}
+```
+
+Constraint/query failure pattern (`query_error`):
+
+Assumes:
+- You created a unique index and applied it (for example via `ensure_table()` + `ensure_indexes()` or `ensure_model()`).
+
+```js
+const unique_user_schema = new JsonBadger.Schema({
+	email: {type: String, required: true}
+});
+unique_user_schema.create_index({
+	using: 'btree',
+	path: 'email',
+	unique: true,
+	name: 'idx_unique_users_email'
+});
+
+const UniqueUser = connection.model({
+	name: 'UniqueUser',
+	schema: unique_user_schema,
+	table_name: 'unique_users'
+});
+await UniqueUser.ensure_table();
+await UniqueUser.ensure_indexes();
+
+await new UniqueUser({email: 'john@example.com'}).save();
+
+try {
+	await new UniqueUser({email: 'john@example.com'}).save();
+} catch(error) {
+	if(error.name === 'query_error') {
+		const error_payload = error.to_json();
+		const cause_message = error_payload.error.details?.cause;
+		// usually includes: duplicate key value violates unique constraint
+	}
+}
+```
+
+## Query Basics (find, find_one, count_documents)
+
+Assumes (for the query sections below):
+- `User` is defined and at least one document was saved (see `## Create and Save Documents`).
+- Examples that filter by `name: 'john'`, `tags`, `orders`, or `payload` assume those fields/values exist in seeded data.
+
+
+```js
+const all_users = await User.find({}).exec();
+
+const found_user = await User.find_one({name: 'john'}).exec();
+
+const by_id_user = await User.find_by_id('1').exec();
+
+const adult_count = await User.count_documents({age: {$gte: 18}}).exec();
+```
+
+Returns:
+- `all_users`: `User[]` (document instances)
+- `found_user`: `User | null`
+- `by_id_user`: `User | null`
+- `adult_count`: `number`
+- Snapshot example: `all_users[0]?.document` -> `{ id, data, created_at, updated_at }` when the default slug is still `data`
 
 Query builder chaining:
 
@@ -244,16 +467,13 @@ const page_of_users = await User.find({status: 'active'})
 	.exec();
 ```
 
-Read behavior note:
-- `find(...).exec()`, `find_one(...).exec()`, and `count_documents(...).exec()` do not call `ensure_table()`.
-
 ## Direct Equality and Scalar Comparisons
 
 Direct equality and explicit `$eq` both work:
 
 ```js
-await User.find({user_name: 'john'}).exec();
-await User.find({user_name: {$eq: 'john'}}).exec();
+await User.find({name: 'john'}).exec();
+await User.find({name: {$eq: 'john'}}).exec();
 ```
 
 Scalar comparison operators:
@@ -273,19 +493,27 @@ await User.find({status: {$in: ['active', 'pending']}}).exec();
 await User.find({status: {$nin: ['disabled', 'banned']}}).exec();
 ```
 
+Reserved base-field filters (top-level only):
+
+```js
+await User.find({id: {$in: [1, 2, 3]}}).exec(); // bigserial default
+await User.find({created_at: {$gte: '2026-01-01T00:00:00.000Z'}}).exec();
+await User.find({updated_at: {$lt: '2026-12-31T23:59:59.999Z'}}).sort({updated_at: -1}).exec();
+```
+
 ## Regex Operators
 
 Regex literal shorthand:
 
 ```js
-await User.find({user_name: /jo/i}).exec();
+await User.find({name: /jo/i}).exec();
 ```
 
 `$regex` with `$options`:
 
 ```js
 await User.find({
-	user_name: {
+	name: {
 		$regex: '^jo',
 		$options: 'i'
 	}
@@ -355,7 +583,7 @@ await User.find({payload: {$has_any_keys: ['profile', 'flags']}}).exec();
 await User.find({payload: {$has_all_keys: ['profile', 'score']}}).exec();
 ```
 
-Nested-scope existence (jsonbadger extracts the nested JSONB value first, then applies top-level existence there):
+Nested-scope existence (JsonBadger extracts the nested JSONB value first, then applies top-level existence there):
 
 ```js
 await User.find({'payload.profile': {$has_key: 'city'}}).exec();
@@ -368,14 +596,14 @@ await User.find({payload: {$has_key: 'profile.city'}}).exec();
 
 `$json_path_exists` (`@?`) and `$json_path_match` (`@@`):
 
-Assumes:
-- Your seeded `payload` includes shapes like `items[*].qty` and `score` (as shown in `## Create and Save Documents`).
-
-Target shape reminder:
-- `payload` is a JSON object with keys like `score` and `items`, where `items` is an array of objects (for example `{qty: 2}`).
-
-```js
-await User.find({
+Assumes:
+- Your seeded `payload` includes shapes like `items[*].qty` and `score` (as shown in `## Create and Save Documents`).
+
+Target shape reminder:
+- `payload` is a JSON object with keys like `score` and `items`, where `items` is an array of objects (for example `{qty: 2}`).
+
+```js
+await User.find({
 	payload: {$json_path_exists: '$.items[*] ? (@.qty > 1)'}
 }).exec();
 
@@ -392,39 +620,41 @@ Expected behavior:
 
 `update_one(...)` supports `$set`, `$insert`, and `$set_lax`.
 
-Assumes (for update and delete sections below):
-- A matching row exists (examples use `user_name: 'john'` and `user_name: 'missing'`).
-- The seeded row includes `tags` and `payload` fields from the create/save example.
-
-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(...)`):
+Assumes (for update and delete sections below):
+- A matching row exists (examples use `name: 'john'` and `name: 'missing'`).
+- The seeded row includes `tags` and `payload` fields from the create/save example.
+
+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(...)`):
 
 ```js
 const updated_user = await User.update_one(
-	{user_name: 'john'},
-	{
-		$set: {
-			age: 31,
+	{name: 'john'},
+	{
+		$set: {
+			age: 31,
 			'profile.city': 'Orlando',
 			'payload.profile.state': 'FL'
-		}
-	}
-);
-// returns: updated data object (plain object) or null
-```
+		}
+	}
+);
+```
+
+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:
 
 ```js
-await User.update_one({user_name: 'john'}, {
+await User.update_one({name: 'john'}, {
 	$insert: {
 		'tags.0': 'first_tag'
 	}
 });
 
-await User.update_one({user_name: 'john'}, {
+await User.update_one({name: 'john'}, {
 	$insert: {
 		'tags.0': {
 			value: 'after_first',
@@ -434,13 +664,13 @@ await User.update_one({user_name: 'john'}, {
 });
 ```
 
-`$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`.
-
-```js
-await User.update_one({user_name: 'john'}, {
+`$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`.
+
+```js
+await User.update_one({name: 'john'}, {
 	$set_lax: {
 		'payload.cleanup_flag': {
 			value: null,
@@ -453,7 +683,7 @@ await User.update_one({user_name: 'john'}, {
 `$set_lax` options example (`create_if_missing`, `null_value_treatment`):
 
 ```js
-await User.update_one({user_name: 'john'}, {
+await User.update_one({name: 'john'}, {
 	$set_lax: {
 		'payload.archived_at': {
 			value: null,
@@ -467,7 +697,7 @@ await User.update_one({user_name: 'john'}, {
 Multiple update operators in one call (application order is `$set` -> `$insert` -> `$set_lax`):
 
 ```js
-await User.update_one({user_name: 'john'}, {
+await User.update_one({name: 'john'}, {
 	$set: {
 		'payload.score': 50
 	},
@@ -486,7 +716,7 @@ await User.update_one({user_name: 'john'}, {
 Conflict rule (rejected before SQL):
 
 ```js
-await User.update_one({user_name: 'john'}, {
+await User.update_one({name: 'john'}, {
 	$set: {
 		payload: {nested: true}
 	},
@@ -497,116 +727,163 @@ await User.update_one({user_name: 'john'}, {
 // throws: conflicting update paths (same path or parent/child overlap)
 ```
 
+Timestamp helper examples on update:
+
+```js
+// Caller-provided updated_at is kept
+await User.update_one({name: 'john'}, {
+	$set: {
+		age: 32,
+		updated_at: '2026-03-03T10:00:00.000Z'
+	}
+});
+
+// Omitted updated_at is auto-refreshed
+await User.update_one({name: 'john'}, {
+	$set: {
+		age: 33
+	}
+});
+```
+
 ## Delete Operations
 
-`delete_one(...)` deletes one matching row and returns the deleted document data.
+`delete_one(...)` deletes one matching row and returns the deleted document instance.
 
-```js
-const deleted_user = await User.delete_one({user_name: 'john'});
-// returns: deleted data object (plain object) or null
-```
+```js
+const deleted_user = await User.delete_one({name: 'john'});
+```
+
+Returns: `deleted_user` is `User | null`.  
+Snapshot shape: `deleted_user?.document` -> `{ id, data, created_at, updated_at }` when the default slug is still `data`.
 
 No match (or missing table) returns `null`:
 
-```js
-const maybe_deleted = await User.delete_one({user_name: 'missing'});
-// returns: null when no row matches (or when the table does not exist yet)
-if(maybe_deleted === null) {
-	// no matching row, or table does not exist yet
-}
+```js
+const maybe_deleted = await User.delete_one({name: 'missing'});
+if(maybe_deleted === null) {
+	// no matching row, or table does not exist yet
+}
 ```
 
-## Runtime Document Methods (get/set, dirty tracking, serialization)
+Returns: `null` when no row matches (or when the table does not exist yet).
+
+## Runtime Document Methods (get/set and direct document access)
 
-Runtime getters/setters and dirty tracking:
+Runtime getters/setters:
 
 Assumes:
-- `User` is defined from the schema/model example and includes the `user_name` getter configuration shown there.
+- `User` is defined from the schema/model example and includes the `name` getter configuration shown there.
 - This snippet demonstrates in-memory runtime behavior; no database read is required until `save()`.
 
 
 ```js
-const doc = new User({
-	user_name: 'jane',
+const doc = User.from({
+	name: 'jane',
 	status: 'active',
 	payload: {count: 1},
 	profile: {city: 'Miami'}
 });
 
-// normal path set/get
+const default_slug = User.schema.get_default_slug();
 
-doc.set('user_name', '  jane_doe  ');
-const upper_name = doc.get('user_name');
+doc.set(default_slug + '.name', '  jane_doe  ');
+const user_name = doc.get(default_slug + '.name');
 
-doc.set('profile.city', 'Orlando');
-const city = doc.get('profile.city');
+doc.set(default_slug + '.profile.city', 'Orlando');
+const city = doc.get(default_slug + '.profile.city');
 
-// dirty tracking
-const before_dirty = doc.is_modified('payload');
-doc.data.payload.count += 1;
-if(!doc.is_modified('payload')) {
-	doc.mark_modified('payload');
-}
-const after_dirty = doc.is_modified('payload');
+// raw document access still works
+doc.document[default_slug].payload.count += 1;
+const pending_delta = doc.document.$get_delta();
+```
+
+Bind live document fields onto another object:
+
+```js
+const user_entity = {};
+doc.bind_document(user_entity);
 
-doc.clear_modified();
+user_entity.name; // reads from the default slug
+user_entity.profile.city = 'Tampa'; // live nested default-slug object
 ```
 
+> **Note:** `bind_document(...)` flattens default-slug root fields onto the target root, but keeps extra slugs nested. It also throws if the target already owns one of the field names it needs to bind.
+
 ### Optional Alias Path Example
 
 Use aliases only when you need an alternate path name (for example, a short path shortcut for a nested field).
 
 ```js
-const alias_schema = new jsonbadger.Schema({
+const alias_schema = new JsonBadger.Schema({
 	profile: {
 		city: {type: String, alias: 'city'}
 	}
 });
 
-const AliasUser = jsonbadger.model('alias_users', alias_schema);
-const alias_doc = new AliasUser({profile: {city: 'Miami'}});
+const AliasUser = connection.model({
+	name: 'AliasUser',
+	schema: alias_schema,
+	table_name: 'alias_users'
+});
+const alias_doc = AliasUser.from({profile: {city: 'Miami'}});
 
 // alias path -> underlying path
 alias_doc.get('city'); // 'Miami'
 alias_doc.set('city', 'Orlando');
-alias_doc.get('profile.city'); // 'Orlando'
+alias_doc.get('data.profile.city'); // 'Orlando' when the default slug is still `data`
 ```
 
-Aliases are path aliases for `doc.get(...)`, `doc.set(...)`, and `doc.mark_modified(...)`. They do not create direct properties (for example, `alias_doc.city`).
+Aliases are schema-defined alternate path names for `doc.get(...)` and `doc.set(...)`. They are collected when the schema is created, while canonical schema paths remain the persisted keys.
 
-Serialization helpers (`to_object`, `to_json`) apply getters by default:
+Immutable behavior (`immutable: true`) after first persist:
 
 ```js
-const as_object = doc.to_object();
-const as_object_without_getters = doc.to_object({getters: false});
-const as_json_ready = doc.to_json();
+await doc.save();
+
+// after successful save, immutable fields reject updates
+// doc.set('status', 'disabled'); // throws
 ```
 
-Immutable behavior (`immutable: true`) after first persist:
+## Lifecycle Quick Reference
 
 ```js
+const doc = User.from({name: 'john'});
+doc.set('data.profile.city', 'Miami');
 await doc.save();
 
-// after successful save, immutable fields reject updates
-// doc.set('status', 'disabled'); // throws
+const found = await User.find_by_id(doc.id).exec();
+const snapshot = found.document;
 ```
 
+Phase summary:
+- `User.from(...)` -> constructed
+- first runtime interaction (`set/get/save/delete`) -> runtime-ready
+- `save()` on new doc -> persisted
+- `find_one(...).exec()` / `find_by_id(...).exec()` -> queried/hydrated
+
+For the full lifecycle contract, see [`docs/lifecycle.md`](lifecycle.md).
+
 ## Complete Operator Checklist (Query and Update)
 
-This page includes examples for:
-- direct equality and `$eq`
-- `$ne`, `$gt`, `$gte`, `$lt`, `$lte`
-- `$in`, `$nin`
-- `$regex` + `$options` (and RegExp literal shorthand)
-- `$all`, `$size`, `$elem_match`
-- `$contains`
-- `$has_key`, `$has_any_keys`, `$has_all_keys`
-- `$json_path_exists`, `$json_path_match`
-- `update_one.$set`, `update_one.$insert`, `update_one.$set_lax`
-
-## Related Docs
+| Family | Supported operators/methods |
+| --- | --- |
+| Scalar equality/comparison | direct equality, `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte` |
+| Set membership | `$in`, `$nin` |
+| Regex | RegExp literal shorthand, `$regex`, `$options` |
+| Array operators | `$all`, `$size`, `$elem_match` |
+| 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` |
+
+## Related Docs
 
 - [`README.md`](../README.md) (quick start + selected examples)
-- [`docs/api.md`](api.md) (API surface and behavior notes)
+- [`docs/api/index.md`](api/index.md) (module API map)
+- [`docs/api/model.md`](api/model.md) (model construction, queries, persistence, and document methods)
+- [`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/local-integration-testing.md`](local-integration-testing.md) (local integration test setup)