jsonbadger 0.5.0 → 0.6.1

package/docs/api/model.md

@@ -0,0 +1,392 @@
+# Model API
+
+Models are created through the owning connection:
+
+```js
+const connection = await JsonBadger.connect(uri, options);
+const user_model = connection.model({name: 'User', schema: user_schema, table_name: 'users'});
+```
+
+## TOC
+
+- [Model API](#model-api)
+- [Construction](#construction)
+- [Ownership Boundary](#ownership-boundary)
+- [Static Methods](#static-methods)
+- [Model.from](#modelfrom)
+- [Model.hydrate](#modelhydrate)
+- [Model.cast](#modelcast)
+- [Instance Methods](#instance-methods)
+- [Related Docs](#related-docs)
+
+## Construction
+
+Build new documents with `Model.from(...)`:
+
+```js
+const user_document = user_model.from({
+	name: 'john',
+	age: 30
+});
+```
+
+Hydrate persisted row-like data with `Model.hydrate(...)`:
+
+```js
+const hydrated_user = user_model.hydrate({
+	id: '7',
+	data: {
+		name: 'maria'
+	},
+	created_at: '2026-03-03T08:00:00.000Z',
+	updated_at: '2026-03-03T09:00:00.000Z'
+});
+```
+
+> **Note:** Prefer `Model.from(...)` and `Model.hydrate(...)` over direct `new Model(...)` construction. Those entry points conform the document envelope, then apply schema defaults, casting, and validation before returning the document instance.
+>
+> Direct `new user_model(document)` construction remains available as a low-level path. It bypasses lifecycle until you call `doc.$conform_document(...)`, `doc.$apply_defaults(...)`, `doc.$cast(...)`, `doc.$validate(...)`, or `doc.$normalize(...)` manually.
+
+## Ownership Boundary
+
+`Model` owns how a schema is persisted and used at runtime.
+
+It is the right place for:
+
+1. `table_name`, `data_column`, and related storage options
+2. Startup/bootstrap helpers such as `ensure_table()`, `ensure_indexes()`, and `ensure_model()`
+3. Query and update entry points
+4. Document construction and row hydration
+
+`Model` consumes a `Schema`; it does not replace it.
+
+## Static Methods
+
+- `Model.create(document_or_list)`
+  - validates and saves one or more documents
+- `Model.find(filter)`
+  - returns a query builder
+- `Model.find_one(filter)`
+  - returns a query builder that resolves to one document or `null`
+- `Model.find_by_id(id_value)`
+  - returns a query builder for one document by top-level `id`
+- `Model.count_documents(filter)`
+  - returns a query builder that resolves to a count
+- `Model.insert_one(input_data)`
+  - inserts one plain payload input and returns the persisted document
+- `Model.update_one(filter, update_definition)`
+  - updates one matching row and returns the updated document or `null`
+- `Model.delete_one(filter)`
+  - deletes one matching row and returns the deleted document or `null`
+- `Model.ensure_table()`
+  - creates the backing table during startup/bootstrap setup
+- `Model.ensure_indexes()`
+  - creates declared indexes during startup/bootstrap setup
+- `Model.ensure_model()`
+  - runs table setup and, when `schema.auto_index` is enabled, declared indexes
+- `Model.from(input_data, options?)`
+  - builds a new document from external payload input without marking it persisted
+- `Model.hydrate(input_data, options?)`
+  - builds a persisted document from existing row-like data with no modified paths
+- `Model.cast(document)`
+  - delegates to `schema.cast(document)`
+
+Example:
+
+```js
+const saved_user = await user_model.create({
+	name: 'maria',
+	age: 29
+});
+
+const found_user = await user_model.find_one({name: 'maria'}).exec();
+```
+
+> **Note:** `Model.insert_one(...)` accepts plain input only. If you already have a document instance, use `doc.insert()` or `doc.save()`.
+
+## Model.from
+
+Use `Model.from(...)` when the source is external payload input and you want a new document:
+
+```js
+const imported_user = user_model.from({
+	name: '  maria  ',
+	age: '29',
+	created_at: '2026-03-03T08:00:00.000Z'
+});
+```
+
+Behavior:
+- returns a new document instance
+- keeps `is_new = true`
+- leaves no paths marked as modified after lifecycle normalization
+- conforms the document envelope, then applies schema defaults, casting, and validation before returning
+- expands dotted payload keys at the input boundary
+- routes root keys listed in `schema.options.slugs` out of the default slug
+- keeps every other non-base root key inside the default slug
+- does not interpret payload input as a persisted row envelope
+
+Input flow:
+1. check whether the input is object-like
+2. serialize non-plain objects through `to_json`, `toJSON`, or `to_plain_object(...)`
+3. expand dotted payload keys into nested objects
+4. route registered extra slug roots out of the default slug
+5. keep every remaining root key in the default slug
+6. build the document instance
+7. conform the document envelope, then apply schema defaults, casting, and validation
+8. clear tracker changes so the normalized state becomes the baseline
+
+Example with a custom default slug:
+
+```js
+const user_schema = new JsonBadger.Schema({
+	name: String,
+	settings: {
+		theme: String
+	}
+}, {
+	default_slug: 'payload',
+	slugs: ['settings']
+});
+
+const user_model = connection.model({
+	name: 'User',
+	schema: user_schema,
+	table_name: 'users'
+});
+
+const imported_user = user_model.from({
+	id: '7',
+	created_at: '2026-03-03T08:00:00.000Z',
+	name: 'maria',
+	settings: {
+		theme: 'dark'
+	}
+});
+```
+
+Result:
+- `imported_user.document.id === '7'`
+- `imported_user.document.created_at instanceof Date`
+- `imported_user.document.payload.name === 'maria'`
+- `imported_user.document.settings.theme === 'dark'`
+
+## Model.hydrate
+
+Use `Model.hydrate(...)` when the source already represents a persisted row:
+
+```js
+const hydrated_user = user_model.hydrate({
+	id: '7',
+	payload: {
+		name: 'maria',
+		age: '29'
+	},
+	settings: {
+		theme: 'dark'
+	},
+	created_at: '2026-03-03T08:00:00.000Z',
+	updated_at: '2026-03-03T09:00:00.000Z'
+});
+```
+
+Behavior:
+- returns a document instance
+- sets `is_new = false`
+- leaves no paths marked as modified initially
+- treats the outer object as the persisted row envelope
+- reads the payload from `input_data[default_slug]`
+- preserves registered extra slug objects as sibling roots
+- ignores unregistered extra root slugs
+- applies schema defaults, casting, and validation before rebasing tracker state
+- does not expand dotted payload keys during hydration
+
+Input flow:
+1. check whether the input is object-like
+2. serialize non-plain objects through `to_json`, `toJSON`, or `to_plain_object(...)`
+3. copy top-level base fields from the row
+4. read `schema.get_slugs()` from the row and default missing slug roots to `{}`
+5. build the document instance
+6. conform the document envelope, then apply schema defaults, casting, and validation
+7. clear tracker changes
+8. mark the document persisted
+
+> **Note:** `Model.hydrate(...)` is strict about row shape. It does not rebuild the default slug from unrelated root keys.
+
+## Model.cast
+
+Use `Model.cast(...)` when you want schema casting without building a document instance:
+
+```js
+const casted_document = user_model.cast({
+	payload: {
+		age: '29'
+	},
+	settings: {
+		count: '7'
+	}
+});
+```
+
+Behavior:
+- delegates to `schema.cast(...)`
+- deep-clones the input document first
+- casts existing base-field, default-slug, and extra-slug values
+- does not validate
+- does not conform
+
+## Instance Methods
+
+- `doc.save()`
+  - inserts a new row or updates an existing persisted document
+- `doc.insert()`
+  - inserts the current document as a new row
+- `doc.update()`
+  - updates the current persisted document by `id`
+- `doc.get(path_name)`
+  - resolves aliases and reads the exact path from `doc.document`
+- `doc.set(path_name, value)`
+  - resolves aliases, applies schema setter/cast logic, and writes the exact path into `doc.document`
+- `doc.$apply_defaults(options?)`
+  - fills missing paths from schema defaults on the current tracked document
+- `doc.$conform_document(options?)`
+  - removes unknown envelope keys from the current tracked document according to schema slugs and paths
+- `doc.$cast(options?)`
+  - applies schema setter/cast logic across the current tracked document
+- `doc.$validate(options?)`
+  - validates the current document envelope against the schema
+- `doc.$normalize(options?)`
+  - runs `$conform_document(...)`, `$apply_defaults(...)`, `$cast(...)`, and `$validate(...)` in order
+- `doc.bind_document(target)`
+  - binds live forwarding properties onto `target` from the current document instance
+- `doc.rebase(reference)`
+  - replaces the current document state from another `Model` or `Document` and clears tracked changes
+- `doc.id`
+- `doc.created_at`
+- `doc.updated_at`
+- `doc.timestamps`
+
+Example:
+
+```js
+const doc = user_model.from({
+	name: 'john',
+	profile: {city: 'Miami'}
+});
+
+const default_slug = user_model.schema.get_default_slug();
+
+doc.set(default_slug + '.profile.city', 'Orlando');
+const city = doc.get(default_slug + '.profile.city');
+
+await doc.save();
+```
+
+Low-level constructor path with manual lifecycle:
+
+```js
+const doc = new user_model({
+	payload: {
+		age: '29'
+	}
+});
+
+doc.$normalize({mode: 'from'});
+```
+
+Behavior:
+- direct `new user_model(document)` keeps the raw tracked state as given
+- conform, defaults, casting, and validation do not run automatically on that low-level path
+- manual lifecycle methods are available when you intentionally want that control
+
+`doc.bind_document(target)` projects live document-backed fields onto another object, such as a domain entity wrapper.
+
+```js
+const doc = user_model.hydrate({
+	id: '7',
+	payload: {
+		name: 'maria',
+		profile: {city: 'Miami'}
+	},
+	settings: {
+		theme: 'dark'
+	}
+});
+
+const entity = {};
+doc.bind_document(entity);
+
+entity.name; // 'maria'
+entity.profile.city = 'Orlando';
+entity.settings.theme = 'light';
+```
+
+Behavior:
+- returns the same `target`
+- flattens default-slug root fields onto the target root
+- keeps extra slugs nested at their slug root
+- returns live tracked objects, not snapshots
+- throws if `target` already owns a conflicting property name
+
+> **Note:** `bind_document(...)` does not create or require `target.model`. It binds directly to the current document instance. To rebind a different document later, clear or replace the old bound properties first, then call `next_doc.bind_document(target)` again.
+
+`doc.rebase(reference)` is useful when you want to keep the same outer object but adopt a fresh persisted document state.
+
+Scenario A: keep a bound entity wrapper and adopt the saved state.
+
+```js
+const doc = user_model.from({
+	name: 'maria',
+	profile: {city: 'Miami'}
+});
+
+const entity = {};
+doc.bind_document(entity);
+
+entity.profile.city = 'Orlando';
+
+const saved_doc = await doc.save();
+doc.rebase(saved_doc);
+```
+
+Scenario B: refresh the current instance from a newer persisted copy.
+
+```js
+const current_doc = await user_model.find_one({id: user_id}).exec();
+const fresh_doc = await user_model.find_one({id: user_id}).exec();
+
+current_doc.rebase(fresh_doc);
+```
+
+Scenario C: adopt a trusted `Document` returned by a custom persistence path.
+
+```js
+const next_document = custom_save_flow(doc.document);
+doc.rebase(next_document);
+```
+
+Behavior:
+- accepts only a `Model` or `Document` reference
+- sets `doc.is_new = false`
+- replaces the current `doc.document` state
+- clears pending tracker changes after rebasing
+
+> **Note:** Use `Model.hydrate(...)` for plain row-like input. `rebase(...)` is for adopting an already-built `Model` or `Document`.
+
+Direct document access:
+
+```js
+const default_slug = user_model.schema.get_default_slug();
+const payload = doc.document[default_slug];
+```
+
+> **Note:** Direct `doc.document[...]` mutation is still allowed, but it bypasses `doc.set(...)` and assignment-time casting.
+
+## Related Docs
+
+- [`connection.md`](connection.md)
+- [`document.md`](document.md)
+- [`schema.md`](schema.md)
+- [`query-builder.md`](query-builder.md)
+- [`../lifecycle.md`](../lifecycle.md)
+- [`../examples.md`](../examples.md)

package/docs/api/query-builder.md

@@ -0,0 +1,81 @@
+# Query Builder API
+
+## TOC
+
+- [Query Builder API](#query-builder-api)
+- [Builder Chain](#builder-chain)
+- [Execution](#execution)
+- [Supported Filter Families](#supported-filter-families)
+- [Base-field Query Rules](#base-field-query-rules)
+- [JSON Key Existence](#json-key-existence)
+- [JSONPath](#jsonpath)
+
+## Builder Chain
+
+- `.where(filter)`
+- `.sort(sort)`
+- `.limit(limit)`
+- `.skip(skip)`
+- `.exec()`
+
+## Execution
+
+```js
+const result = await user_model.find({status: 'active'}).sort({created_at: -1}).limit(10).exec();
+```
+
+Filter objects must be plain JSON-like objects:
+- use object literals for operator objects like `{age: {$gte: 18}}`
+- use plain nested objects for JSON containment filters
+- use plain objects instead of custom class instances for operator objects
+
+> **Note:** Base-field operator objects and nested filter objects only accept plain objects with a default or null prototype.
+
+Read/query execution:
+- `find(...).exec()`
+- `find_one(...).exec()`
+- `find_by_id(...).exec()`
+- `count_documents(...).exec()`
+
+> **Note:** Query builders are not thenables. Call `.exec()`.
+
+## Supported Filter Families
+
+- scalar comparisons: direct equality, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`
+- sets/arrays: `$in`, `$nin`, `$all`, `$size`, `$contains`, `$elem_match`
+- regex: `$regex` and `$options`
+- 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.
+
+## Base-field Query Rules
+
+Top-level base fields:
+- `id`
+- `created_at`
+- `updated_at`
+
+Rules:
+- top-level base fields map to row columns
+- dotted base-field paths are rejected
+
+Operator matrix:
+- `id`: direct equality, `$eq`, `$ne`, `$in`, `$nin`
+- `created_at` / `updated_at`: direct equality, `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`
+- unsupported on base fields: `$regex`, `$contains`, `$all`, `$size`, `$has_key`, `$has_any_keys`, `$has_all_keys`, `$json_path_exists`, `$json_path_match`, `$elem_match`
+
+## JSON Key Existence
+
+- `$has_key` maps to PostgreSQL `?`
+- `$has_any_keys` maps to PostgreSQL `?|`
+- `$has_all_keys` maps to PostgreSQL `?&`
+
+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.

package/docs/api/schema.md

@@ -0,0 +1,204 @@
+# Schema API
+
+## TOC
+
+- [Schema API](#schema-api)
+- [Constructor](#constructor)
+- [Ownership Boundary](#ownership-boundary)
+- [Core Methods](#core-methods)
+- [Slug Access](#slug-access)
+- [Casting and Validation](#casting-and-validation)
+- [create_index](#create_index)
+- [add_method](#add_method)
+- [Path-level Index Sugar](#path-level-index-sugar)
+
+## Constructor
+
+```js
+const user_schema = new JsonBadger.Schema(definition, options);
+```
+
+## Ownership Boundary
+
+`Schema` defines what a document looks like.
+
+It is the right place for:
+
+1. Field definitions
+2. Validation and path introspection
+3. Schema-declared indexes
+4. Schema-level document methods
+5. Slug ownership and validator domains
+
+Use `Schema` to define document structure and behavior. Specify table names, connection details, and other storage options later when you register the model through `connection.model(...)`.
+
+`definition` must be a plain JSON-like object:
+- use object literals for nested schema branches
+- use field definitions like `{type: String, required: true}`
+- avoid custom class instances for schema definition objects
+
+> **Note:** JsonBadger treats only default-prototype or null-prototype objects as plain schema objects. Custom instances are not parsed as nested schema branches.
+
+## Core Methods
+
+- `validate(document)`
+- `validate_base_fields(document)`
+- `cast(document)`
+- `conform(document)`
+- `get_path(path)`
+- `get_path_type(path)`
+- `is_array_root(path)`
+- `create_index(index_definition)`
+- `get_indexes()`
+- `add_method(name, method_implementation)`
+
+Base-field notes:
+- `id`, `created_at`, and `updated_at` exist in schema/runtime introspection
+- if user schema declares those base fields, user definitions are preserved
+- `validate(document)` validates the full document envelope, not just the default slug
+- when a schema registers extra root slugs through `schema.options.slugs`, validation fans out across those document roots
+
+## Slug Access
+
+Read slug ownership directly from the schema:
+
+```js
+const default_slug = schema.get_default_slug();
+const extra_slugs = schema.get_extra_slugs();
+const all_slugs = schema.get_slugs();
+```
+
+Rules:
+- `get_default_slug()` returns the catch-all payload root
+- `get_extra_slugs()` returns only explicitly registered sibling roots
+- `get_slugs()` returns `[default_slug, ...extra_slugs]`
+- duplicate extra slugs are collapsed during schema option normalization
+
+## Casting and Validation
+
+Validate a full document envelope:
+
+```js
+schema.validate({
+	id: '0194f028-579a-7b5b-8107-b9ad31395f43',
+	payload: {
+		name: 'maria'
+	},
+	settings: {
+		theme: 'dark'
+	}
+});
+```
+
+Validate only root base fields:
+
+```js
+schema.validate_base_fields({
+	id: '0194f028-579a-7b5b-8107-b9ad31395f43',
+	created_at: '2026-03-03T08:00:00.000Z',
+	updated_at: '2026-03-03T09:00:00.000Z'
+});
+```
+
+Cast a document envelope without validating or conforming:
+
+```js
+const casted_document = schema.cast({
+	payload: {
+		age: '29'
+	},
+	settings: {
+		count: '7'
+	}
+});
+```
+
+Behavior:
+- `schema.cast(...)` deep-clones the input first
+- casts existing base-field, default-slug, and extra-slug values
+- leaves missing paths untouched
+- does not validate
+- does not conform
+
+Conform one document envelope to the schema-owned allowed tree:
+
+```js
+const document = {
+	payload: {
+		name: 'nell',
+		unknown_key: true
+	},
+	settings: {
+		theme: 'dark',
+		rogue: true
+	}
+};
+
+schema.conform(document);
+```
+
+After conforming:
+- known keys remain
+- unknown keys are removed
+
+## create_index
+
+GIN single-path index:
+
+```js
+schema.create_index({using: 'gin', path: 'profile.city', name: 'idx_users_city_gin'});
+```
+
+BTREE single-path index:
+
+```js
+schema.create_index({using: 'btree', path: 'age', order: -1, unique: true});
+```
+
+BTREE compound index:
+
+```js
+schema.create_index({using: 'btree', paths: {name: 1, type: -1}, unique: true, name: 'idx_name_type'});
+```
+
+Rules:
+- `using: 'gin'` requires `path`
+- `using: 'gin'` ignores `order` and `unique`
+- `using: 'btree'` requires `path` or `paths`
+- `order` is only valid when using a single `path` with `using: 'btree'`
+
+## add_method
+
+Install a custom document-instance method onto models generated from the schema.
+
+```js
+schema.add_method('full_name', function () {
+	const default_slug = this.constructor.schema.get_default_slug();
+	const payload = this.document[default_slug];
+	return payload.first_name + ' ' + payload.last_name;
+});
+```
+
+Rules:
+- `name` must be a valid identifier
+- `method_implementation` must be a function
+- duplicate schema method names are rejected
+- names that conflict with built-in document properties are rejected when the model is created
+
+## Path-level Index Sugar
+
+Examples:
+
+```js
+{
+	name: {type: String, index: true},
+	age: {type: Number, index: 1},
+	score: {type: Number, index: -1},
+	email: {type: String, index: {unique: true, name: 'idx_users_email_unique'}},
+	nick_name: {type: String, index: {using: 'gin'}}
+}
+```
+
+Normalization notes:
+- object-form `index` defaults to `btree` unless `using` says otherwise
+- invalid or unsupported inline index values are ignored permissively