jsonbadger 0.5.0 → 0.6.1

package/README.md

@@ -29,35 +29,38 @@ npm install jsonbadger
 ## Examples (Quick Start)
 
 ```js
-import jsonbadger from 'jsonbadger';
+import JsonBadger from 'jsonbadger';
 
 // 1. Connect to database
-await jsonbadger.connect('postgresql://user:pass@localhost:5432/dbname', {
+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 // server default: bigserial | uuidv7 (native PostgreSQL uuidv7() required)
-});
+	auto_index: true
+};
+const connection = await JsonBadger.connect(db_uri, options);
 
 // 2. Define schema (FieldType format)
-const user_schema = new jsonbadger.Schema({
-	user_name: {type: String, required: true, index: true},
+const user_schema = new JsonBadger.Schema({
+	name: {type: String, required: true, index: true},
 	age: {type: Number, min: 0, index: -1},
 	type: {type: String},
 	email: {type: String, index: {unique: true, name: 'idx_users_email_unique'}}
+}, {
+	id_strategy: JsonBadger.IdStrategies.bigserial
 });
 
 // 3. Declare indexes on schema (path-level + schema-level compound index)
-// Object-form create_index(...) is how you define a compound index.
-user_schema.create_index({user_name: 1, type: -1});
+// Descriptor-form create_index(...) is how you define explicit index declarations.
+user_schema.create_index({using: 'btree', paths: {name: 1, type: -1}});
 
 // 4. Create model
-const User = jsonbadger.model(user_schema, {
+const User = connection.model({
+	name: 'User',
+	schema: user_schema,
 	table_name: 'users',
-	data_column: 'data',
-	auto_index: false, // optional model-level override
-	id_strategy: jsonbadger.IdStrategies.bigserial // optional model-level override (uuidv7 uses DB-generated ids)
+	auto_index: false // optional model-level override
 });
 
 // 5. Run migrations manually (optional if you rely on first-write auto table creation via save()/update_one())
@@ -66,23 +69,29 @@ await User.ensure_index();
 
 // 6. Save a document
 const saved_user = await new User({
-	user_name: 'john',
+	name: 'john',
 	age: 30,
 	type: 'admin'
 }).save();
+// returns: User document instance
+// saved_user.to_json() -> { id, name, age, type, created_at, updated_at }
 
 // 7. Find a document
 const found_user = await User.find_one({
-	user_name: 'john'
+	name: 'john'
 }).exec();
+// returns: User document instance or null
+// found_user?.to_json() -> { id, name, age, type, created_at, updated_at }
 ```
 
-When using `IdStrategies.uuidv7`, jsonbadger checks PostgreSQL native `uuidv7()` support automatically during `connect(...)` and reuses cached capability metadata for later model-level `uuidv7` overrides. You do not need to run manual version checks; `SELECT version();` and `SHOW server_version;` are optional troubleshooting commands only.
+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.
 
 ## Examples Cheat Sheet
 
 For a complete copy-paste operator and runtime cheat sheet (queries, updates, and document methods), see [`docs/examples.md`](docs/examples.md).
 
+For the document state flow from `new Model(...)` through `save()`, hydration, dirty tracking, and serialization, see [`docs/lifecycle.md`](docs/lifecycle.md).
+
 ## Core Features
 
 * **JSONB-first**: Model API designed specifically for PostgreSQL JSONB.
@@ -92,14 +101,23 @@ For a complete copy-paste operator and runtime cheat sheet (queries, updates, an
 * **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).
+* **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.
+* **UUIDv7 compatibility gating**: JsonBadger checks support automatically and fails early with server version/capability context 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.
 
 ## Documentation
 
-* [`docs/api.md`](docs/api.md)
+* [`docs/api/index.md`](docs/api/index.md)
+* [`docs/api/model.md`](docs/api/model.md) (model construction, queries, persistence, and document methods)
+* [`docs/api/schema.md`](docs/api/schema.md)
+* [`docs/api/query-builder.md`](docs/api/query-builder.md)
+* [`docs/api/connection.md`](docs/api/connection.md) (connection API, lifecycle, and shared-connection examples)
+* [`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/local-integration-testing.md`](docs/local-integration-testing.md)
 * [`CHANGELOG.md`](CHANGELOG.md) for release notes and version history

package/docs/api/connection.md

@@ -0,0 +1,144 @@
+# Connection API
+
+## TOC
+
+- [Connection API](#connection-api)
+- [connect](#connect)
+- [Connection Options](#connection-options)
+- [Connection Lifecycle](#connection-lifecycle)
+- [UUIDv7 Compatibility](#uuidv7-compatibility)
+- [Connection Reuse Pattern](#connection-reuse-pattern)
+- [Cross-File Example](#cross-file-example)
+
+## connect
+
+```js
+const connection = await JsonBadger.connect(uri, options);
+```
+
+`connect(...)` opens a PostgreSQL pool and returns a `Connection` instance.
+
+## Connection 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
+
+Close the connection through the returned instance:
+
+```js
+const connection = await JsonBadger.connect(uri, options);
+await connection.disconnect();
+```
+
+## UUIDv7 Compatibility
+
+- `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.
+
+## Connection Reuse Pattern
+
+If your app wants one shared connection, keep the returned instance and reuse it explicitly.
+
+```js
+import JsonBadger from 'jsonbadger';
+
+let shared_connection = null;
+
+export async function connect_db() {
+	if(shared_connection) {
+		return shared_connection;
+	}
+
+	const uri = 'postgresql://user:pass@localhost:5432/dbname';
+	const options = {max: 10, debug: false};
+
+	shared_connection = await JsonBadger.connect(uri, options);
+	return shared_connection;
+}
+```
+
+Repeated calls to your own bootstrap helper reuse the same connection:
+
+```js
+const connection_a = await connect_db();
+const connection_b = await connect_db();
+
+connection_a === connection_b;
+// returns: true
+```
+
+## Cross-File Example
+
+Keep the connection bootstrap separate from model and controller code.
+
+`config/db.js`
+
+```js
+import JsonBadger from 'jsonbadger';
+
+let shared_connection = null;
+
+export async function connect_db() {
+	if(shared_connection) {
+		return shared_connection;
+	}
+
+	const uri = 'postgresql://user:pass@localhost:5432/dbname';
+	const options = {max: 10, debug: false};
+
+	shared_connection = await JsonBadger.connect(uri, options);
+	return shared_connection;
+}
+```
+
+`models/user-model.js`
+
+```js
+import JsonBadger from 'jsonbadger';
+import {connect_db} from '../config/db.js';
+
+const connection = await connect_db();
+const user_schema = new JsonBadger.Schema({
+	username: {type: String, required: true, index: true},
+	email: {type: String, required: true, index: {unique: true, name: 'idx_users_email_unique'}}
+});
+
+export const user_model = connection.model({name: 'User', schema: user_schema, table_name: 'users'});
+```
+
+`controllers/user-controller.js`
+
+```js
+import {user_model} from '../models/user-model.js';
+
+export async function get_users(req, res) {
+	const users = await user_model.find({}).exec();
+	return res.json(users);
+}
+```
+
+`app.js`
+
+```js
+import express from 'express';
+import {connect_db} from './config/db.js';
+import {get_users} from './controllers/user-controller.js';
+
+const app = express();
+
+await connect_db();
+
+app.get('/users', get_users);
+app.listen(3000);
+```
+
+What to expect:
+- `find(...).exec()` returns document instances
+- `find_one(...).exec()` returns one document instance or `null`
+- `save()`, `update_one(...)`, and `delete_one(...)` return document instances

package/docs/api/delta-tracker.md

@@ -0,0 +1,106 @@
+# DeltaTracker
+
+Use `DeltaTracker` to watch object changes and export them as one delta snapshot.
+
+## Example
+
+```js
+const tracker = DeltaTracker({
+	payload: {
+		profile: {
+			name: 'John'
+		}
+	}
+}, {
+	track: ['payload']
+});
+
+tracker.payload.profile.name = 'Jane';
+delete tracker.payload.profile.age;
+
+const delta = tracker.$get_delta();
+
+// {
+//   replace_roots: {},
+//   set: {'payload.profile.name': 'Jane'},
+//   unset: ['payload.profile.age']
+// }
+```
+
+> **Note:** When you use `track: ['payload']`, emitted paths stay rooted at `payload.*`. Downstream code decides whether to keep or strip that root at the handoff boundary.
+
+> **Note:** `payload` is only an example tracked root here. In model/runtime code, the tracked roots come from the configured slug list.
+
+## What It Does
+
+`DeltaTracker` keeps three kinds of change state:
+1. `replace_roots`: full tracked-root replacements.
+2. `set`: path-to-value assignments.
+3. `unset`: removed paths.
+
+It also collapses conflicting nested changes so the exported delta stays logically consistent.
+
+## Current API
+
+### `DeltaTracker(target, options)`
+
+Create one tracked proxy around `target`.
+
+Current options:
+1. `track`: top-level keys to track.
+2. `watch`: watcher configuration.
+3. `intercept_set`: transform assigned values before they are recorded.
+
+### `tracker.$get_delta()`
+
+Return the current delta snapshot:
+
+```js
+{
+	replace_roots: {},
+	set: {},
+	unset: []
+}
+```
+
+### `DeltaTracker.from(object)`
+
+Build one delta from plain input against an empty baseline.
+
+```js
+const delta = DeltaTracker.from({
+	payload: {
+		profile: {
+			name: 'Jane'
+		}
+	}
+});
+```
+
+> **Note:** `DeltaTracker.from(...)` supports nested objects and direct top-level keys. It does not interpret dot-path keys like `'data.profile.name'`.
+
+## Behavior Notes
+
+1. Assigning `undefined` is treated like deletion.
+2. Array `length` writes are ignored.
+3. Replacing a tracked root records one `replace_roots` entry and clears nested child deltas under that root.
+
+## Boundary Notes
+
+`DeltaTracker` stays generic and reusable. It does not know about document-layer SRP, JSONB slugs, or SQL compilation. The model layer configures tracked roots and hands the exported delta to the next boundary.
+
+## Planned Export Options
+
+Future work is expected to stay on the same `get_delta(...options)` method instead of adding multiple export methods.
+
+Planned shapes:
+
+```js
+tracker.$get_delta({strip_roots: true});
+// strip all tracked roots
+
+tracker.$get_delta({strip_roots: ['data']});
+// strip only selected tracked roots
+```
+
+These options are not implemented yet. They are the planned handoff boundary for consumers that need root-relative paths.

package/docs/api/document.md

@@ -0,0 +1,77 @@
+# Document API
+
+`Document` is the plain runtime container behind every model instance.
+
+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(...)`.
+
+## TOC
+
+- [Document API](#document-api)
+- [Construction](#construction)
+- [Instance Methods](#instance-methods)
+- [Related Docs](#related-docs)
+
+## Construction
+
+Create a document from normalized root state:
+
+```js
+import Document from '#src/model/document.js';
+
+const document = new Document({
+	id: '9',
+	payload: {
+		name: 'alice'
+	},
+	settings: {
+		theme: 'dark'
+	},
+	created_at: '2026-03-03T08:00:00.000Z',
+	updated_at: '2026-03-03T09:00:00.000Z'
+});
+```
+
+> **Note:** `Document` does not validate, cast, or normalize external input. If the source is not already trusted runtime state, prefer `Model.from(...)` or `Model.hydrate(...)`.
+
+## Instance Methods
+
+- `document.init(data)`
+  - applies replacement state onto the same document instance
+- `document.get(path_name)`
+  - reads one exact root or nested path
+- `document.set(path_name, value)`
+  - writes one exact root or nested path
+- `document.id`
+- `document.created_at`
+- `document.updated_at`
+
+Example:
+
+```js
+const document = new Document({
+	payload: {
+		profile: {
+			city: 'Miami'
+		}
+	}
+});
+
+document.get('payload.profile.city'); // 'Miami'
+
+document.set('payload.profile.city', 'Madrid');
+document.set('settings.theme', 'dark');
+```
+
+Behavior:
+- keeps document state at the root level
+- supports exact-path reads and writes
+- returns the same instance from `init(...)` and `set(...)`
+- returns `undefined` when `get(...)` reads a missing path
+
+## Related Docs
+
+- [`model.md`](model.md)
+- [`schema.md`](schema.md)
+- [`../lifecycle.md`](../lifecycle.md)