typed_eav 0.8.0 → 0.8.1

data/docs/index.md

@@ -0,0 +1,44 @@
+---
+title: "Documentation"
+nav_group: Start here
+---
+
+# TypedEAV documentation
+
+Add runtime-defined custom fields to Active Record models using native PostgreSQL
+columns for scalar values and JSONB for collections. Define fields globally or
+per tenant, validate input, and query values through Active Record relations.
+
+## Start here
+
+1. [Install and try TypedEAV](getting-started.md).
+2. [Define fields, assign values, and build forms](guides/usage.md).
+3. [Configure tenant scoping](guides/scoping.md) if your application has tenants.
+4. [Filter, sort, and summarize values](guides/queries.md).
+
+## Guides
+
+| Task | Guide |
+|---|---|
+| Choose field types and create custom types | [Fields and validation](guides/fields.md) |
+| Build forms, manage fields, and inspect pending changes | [Reading, writing, and forms](guides/usage.md) |
+| Configure tenants and inspect effective definitions | [Scoping and partitions](guides/scoping.md) |
+| Search and summarize custom values | [Queries](guides/queries.md) |
+| Read and update many records | [Bulk operations](guides/bulk-operations.md) |
+| Map CSV rows to custom fields | [CSV mapping](guides/csv-import.md) |
+| Move field definitions between environments | [Schema portability](guides/schema.md) |
+| React to changes and keep audit history | [Events and versioning](guides/events-and-versioning.md) |
+| Evaluate indexes and performance tradeoffs | [Storage and performance](guides/performance.md) |
+| Upgrade an existing installation | [Upgrading](guides/upgrading.md) |
+
+## Reference and development
+
+- [Public API and configuration](reference/index.md)
+- [Architecture](guides/architecture.md) and [design decisions](adr/index.md)
+- [Development and test isolation](guides/development.md)
+- [Maintaining and publishing these docs](maintaining.md)
+- [Changelog](changelog.md)
+- [Source and issues](https://github.com/dchuk/typed_eav)
+
+These pages describe the code on the default branch. Check the changelog and
+release tag when using an older gem version.

data/docs/maintaining.md

@@ -0,0 +1,82 @@
+---
+title: "Maintainers"
+---
+
+# Maintaining and publishing the documentation
+
+## Update docs with the API
+
+Review documentation after every repository change, including code, tests, dependencies,
+configuration, tooling, CI, migrations, and releases. Update affected pages in
+the same change; if reader-facing behavior is unchanged, explain why no docs
+update was needed in the handoff. Record user-visible changes in the root
+`CHANGELOG.md` under Unreleased. A public API change includes its documentation
+in the same change. Keep the
+README focused on installation and discovery; maintain detailed usage here.
+
+For each public capability, document a practical example, accepted inputs and
+defaults, return value, and relevant failure behavior. Link its API reference to
+its guide. Check claims against implementation and specs, especially transaction,
+NULL, tenant, and callback behavior. A method being mentioned is not sufficient
+coverage if users cannot work out how to call it.
+
+Add new pages to the [documentation home](index.md) or the
+[reference index](reference/index.md). Keep Markdown links relative between
+published pages; `jekyll-relative-links` converts them to site URLs. Link to
+GitHub for files outside `docs/`. Give new pages YAML front matter with a title
+so Jekyll renders them. The sidebar automatically lists pages by `nav_group`
+(assigned by folder defaults in `_config.yml`, or overridden in front matter).
+Use `nav_exclude: true` for supporting pages that should be reachable only through
+a summary page. Individual ADRs use this setting; their user-facing summary
+appears once under Project. The active page is highlighted; mobile navigation uses an expandable menu.
+
+The [changelog](changelog.md) is generated at build time from the root
+`CHANGELOG.md` by `_plugins/changelog.rb`. Edit that source file only and rebuild
+to preview changes. The workflow also runs when that file changes. Use ordinary Markdown headings and fenced examples.
+
+## Preview locally
+
+The documentation dependencies are isolated from the gem's development bundle.
+From the gem repository:
+
+```sh
+cd docs
+bundle install
+bundle exec jekyll serve
+```
+
+Open `http://localhost:4000/typed_eav/`. The default layout uses the Minima theme;
+there is no separate frontend application to maintain.
+
+To build and check links from the repository root:
+
+```sh
+BUNDLE_GEMFILE=docs/Gemfile bundle exec jekyll build --source docs --destination docs/_site
+python3 script/check_docs_site.py docs/_site /typed_eav
+```
+
+The checker verifies local page/asset targets and heading anchors in generated
+HTML. It does not make network requests or certify the accuracy of examples.
+Review examples against the relevant gem specs as part of each change.
+
+## Publish on GitHub Pages
+
+The repository includes `.github/workflows/docs.yml`. Pull requests build and
+check the site; pushes to `main` and manual runs on `main` also deploy it.
+
+1. Commit and push the documentation and workflow to the gem repository.
+2. In the repository's **Settings → Pages**, set **Source** to **GitHub Actions**.
+3. Run the **Documentation** workflow on `main`, or push a documentation change.
+4. Check the deployment URL in the workflow's `github-pages` environment.
+
+The configured project URL is `https://dchuk.github.io/typed_eav/`. It becomes
+available after the first successful deployment. For a different repository or
+custom domain, update `url` and `baseurl` in `_config.yml` and the link-check
+prefix in the workflow.
+
+The site includes guides, references, and ADRs. Internal goal plans and
+`improvement-program.md` are excluded, as are dependency and build files. Build
+output is ignored by Git; GitHub Actions uploads the generated site directly.
+
+See GitHub's [custom Pages workflow documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages)
+for repository permissions and deployment settings.

data/docs/reference/api.md

@@ -0,0 +1,133 @@
+---
+title: "Public API reference"
+---
+
+# Public API reference
+
+This is an index of application-facing entry points. Linked guides explain
+examples, supported types, validation, and transaction boundaries. Internal
+query builders, dispatchers, caches, and callback methods are not extension APIs.
+
+## Host models and records
+
+Declare `has_typed_eav(scope_method: nil, parent_scope_method: nil, types: nil,
+versioned: false)` on an Active Record model. Scope methods name record accessors;
+`parent_scope_method` requires `scope_method`. `types: nil` allows registered
+types; an array restricts them. Versioning additionally requires the global
+boot-time switch. Use the host's `polymorphic_name` for `entity_type`.
+
+| Record method | Contract |
+| --- | --- |
+| `typed_values` | Active Record association; normal saves validate and persist values with the host. |
+| `typed_eav_definitions` | Visible definitions for this record's partition, including same-name candidates. |
+| `typed_eav_scope`, `typed_eav_parent_scope` | Configured accessor values normalized to strings, or `nil`. |
+| `initialize_typed_values` | Build missing effective fields with defaults in memory; returns `typed_values`. Save separately. |
+| `typed_eav_value(name)` | Logical Ruby value, or `nil` when absent. |
+| `set_typed_eav_value(name, value)` | Stage a value by effective field name; unknown names are ignored. Save separately. |
+| `typed_eav_hash` | Hash of field names to logical values. |
+| `typed_eav_attributes=` / `typed_eav=` | Named entries such as `[{name: "age", value: 30}]`; supports `_destroy`. |
+| `typed_values_attributes=` | Rails nested attributes using `field_id`, optional Value `id`, `value`, and `_destroy`. |
+| `typed_eav_changes` | Pending logical changes as `{name => [before, after]}`. |
+| `saved_typed_eav_changes` | Logical changes from the latest successful host save; reload/rollback clears them. |
+
+See [reading, writing, and forms](../guides/usage.md),
+[defaults](../guides/usage.md#defaults-for-new-and-existing-records), and [scoping](../guides/scoping.md).
+
+## Host queries
+
+These methods are available on the host class and through Active Record relations.
+The query methods below (including `typed_eav_definitions`) accept `scope:` and
+`parent_scope:`. Omitted keywords use ambient resolution; explicit `nil` selects
+the global axis. These select **field definitions**, not authorized host rows:
+start with an appropriately filtered host relation.
+
+| Method | Result and defaults |
+| --- | --- |
+| `where_typed_eav(*filters, include_missing: false)` | Active Record relation; filters use `name`, `op` (default `:eq`), and `value`. |
+| `with_field(name, operator_or_value = nil, value = nil, include_missing: false)` | Single-filter relation; two-argument non-Symbol value implies equality. |
+| `order_typed_eav(name, direction: :asc, nulls: :last)` | Relation ordered by a supported scalar field, then host primary key. Replaces prior ordering. |
+| `distinct_typed_eav_values(name, limit: 100)` | Array of distinct scalar values in database order. |
+| `count_distinct_typed_eav_values(name)` | Integer distinct count, including an explicit NULL category. |
+| `typed_eav_value_counts(name, limit: 100)` | Hash of scalar values to counts. |
+| `aggregate_typed_eav(name, operation:)` | `:min`, `:max`, or `:sum` for Integer/Decimal/Percentage; typed number or `nil` for empty min/max. |
+| `typed_eav_definitions` | Relation of visible field definitions; does not collapse names. |
+
+Missing rows differ from explicit NULL rows. `include_missing: true` broadens
+`:is_null` and is ignored by other operators. Scalar APIs reject unsupported
+field families and all-partition ambiguity with `ArgumentError`. See
+[queries](../guides/queries.md) for operators, NULL behavior, limits, and errors.
+
+## Bulk operations
+
+| Host class method | Result and defaults |
+| --- | --- |
+| `typed_eav_hash_for(records, fields: nil, source: :database)` | `{record.id => {field_name => value}}`; optional selected field names; `source: :preloaded` reads loaded associations. |
+| `bulk_set_typed_eav_values(records, values_by_field_name, version_grouping: :default, transaction: :all, chunk_size: nil)` | Normal host saves; returns `{successes: [...], errors_by_record: {record => errors_hash}}`. |
+| `bulk_set_typed_eav_values_per_record(values_by_record, version_grouping: :default, transaction: :all, chunk_size: nil)` | Same result, with `{record => {field_name => value}}` input. |
+| `bulk_upsert_typed_eav_values(records, values_by_field_name, acknowledge_reduced_semantics: false, transaction: :all, chunk_size: nil)` | Written row count; requires explicit acknowledgement, skips persistence callbacks and audit versions. |
+
+Normal bulk writes collect validation failures per record; an unexpected exception
+can roll back the active transaction. `transaction: :chunks` requires a positive
+`chunk_size`; prior chunks remain committed on later failure. See
+[bulk operations](../guides/bulk-operations.md) before choosing either write path.
+
+## Field definitions and values
+
+Use `TypedEAV::Field::<Type>.create!` and ordinary Active Record updates for field
+metadata; `field_options` holds Select/MultiSelect choices. The
+[fields guide](../guides/fields.md) covers every built-in type and its options.
+
+| API | Purpose |
+| --- | --- |
+| `field.default_value` / `default_value=` | Read/set the logical default. Explicit value assignment can override it with `nil`. |
+| `field.backfill_default!(relation: nil)` | Synchronously apply a configured default to eligible existing hosts in batches; no count/result contract. |
+| `field.destroy!` | Apply the field's `field_dependent` policy. |
+| `field.destroy_with_values_in_batches!(batch_size: 1_000)` | Resumable deletion for persisted `field_dependent: :destroy` fields; requires no open transaction. |
+| `field.move_higher`, `move_lower`, `move_to_top`, `move_to_bottom`, `insert_at(position)` | Reorder within the field's partition. |
+| `field.field_type_name`, `display_name`, `array_field?`, `optionable?`, `allowed_option_values` | Metadata for rendering and field-management interfaces. |
+| `field.cast(raw)` | Custom-type protocol returning `[cast_value, invalid]`; casting alone does not establish validity. |
+| `value.value` / `value=` | Read/write the field's logical value, including multi-cell types. |
+| `value.history` | Versions ordered newest first by timestamp and ID. |
+| `value.revert_to(version)` | Save the version's **before** state and write a new version; rejects another Value's version, create versions, and destroyed source Values. |
+
+See [default initialization and backfill](../guides/usage.md#defaults-for-new-and-existing-records),
+[field deletion](../guides/events-and-versioning.md#public-callback-slots), and
+[custom types](../guides/fields.md#custom-field-types) for their contracts. Full history after Value deletion requires querying
+`TypedEAV::ValueVersion` by entity and field identity; see
+[events and versioning](../guides/events-and-versioning.md).
+
+## Schema and CSV
+
+| API | Result |
+| --- | --- |
+| `TypedEAV::SchemaPortability.export_schema(entity_type:, scope: nil, parent_scope: nil)` | String-keyed versioned schema Hash for an exact partition, including fields and sections; excludes values. |
+| `TypedEAV::SchemaPortability.preview_schema(hash, on_conflict: :error)` | Read-only JSON-safe comparison and predicted actions; advisory, not a reservation or validation guarantee. |
+| `TypedEAV::SchemaPortability.import_schema(hash, on_conflict: :error)` | Counts under `"created"`, `"updated"`, `"skipped"`, `"unchanged"`, plus `"errors"`; import runs in a transaction and failures can raise. |
+| `TypedEAV::SchemaPortability.export_snapshot_schema(entity_type:, scope: nil, parent_scope: nil)` | Lean versioned field projection; not a full import payload or a value backup. |
+| `TypedEAV::CSVMapper.row_to_attributes(row, mapping, fields_by_name: nil)` | Result with frozen `attributes`/`errors` Hashes and `success?`/`failure?`. Does not save records. |
+
+`Field::Base.export_schema` and `.import_schema` remain compatible delegators.
+Conflict policies are `:error`, `:skip`, and `:overwrite`; type swaps are refused.
+CSV mapping uses uniformly String header keys or Integer index keys, with field
+names as values. Typed mode casts via supplied definitions, reports cast errors,
+and skips unknown fields. Normal model validation must still run.
+See [schema portability](../guides/schema.md) and [CSV imports](../guides/csv-import.md).
+
+## Partition helpers
+
+`TypedEAV::Partition` expects explicitly resolved scope values; it does not consult
+ambient scope. Visibility methods accept `scope: nil`, `parent_scope: nil`, and
+`mode: :partition`. Use `mode: :all_partitions` only for an authorized admin bypass.
+Invalid modes and orphan parent scopes raise `ArgumentError` in partition mode.
+
+| Method | Result |
+| --- | --- |
+| `visible_fields(entity_type: nil, ...)` | Field relation, including global, scope-only, and full-tuple candidates. |
+| `effective_fields_by_name(entity_type:, ...)` | `{name => field}` with most-specific precedence; all-partitions mode instead returns `{name => [fields]}`. |
+| `definitions_by_name(defs)` | Collapse supplied definitions by name, most-specific winning. Supply only the intended visible set. |
+| `definitions_multimap_by_name(defs)` | Group supplied definitions as `{name => [fields]}` without collapsing. |
+| `visible_sections(entity_type:, ...)` | Relation of sections visible to the tuple. |
+| `find_visible_section!(id, entity_type:, ...)` | Visible Section, or `ActiveRecord::RecordNotFound`. |
+
+These helpers constrain definition visibility; application authorization still
+belongs to the caller. See [scoping](../guides/scoping.md).

data/docs/reference/configuration.md

@@ -0,0 +1,64 @@
+---
+title: "Configuration reference"
+---
+
+# Configuration reference
+
+Configure the gem in a Rails initializer:
+
+```ruby
+TypedEAV.configure do |config|
+  config.scope_resolver = -> { [Current.account&.id, Current.workspace&.id] }
+  config.require_scope = true
+end
+```
+
+The example assumes those are the same partition identifiers returned by the
+host's declared accessors. `TypedEAV.config` returns the configuration object;
+`configure` also accepts a block.
+
+| Setting | Default | Contract |
+| --- | --- | --- |
+| `scope_resolver` | Auto-detect `ActsAsTenant` | Callable returning `nil` or exactly `[scope, parent_scope]`. Default returns `[ActsAsTenant.current_tenant, nil]` when available, otherwise `nil`. Bare scalars raise `ArgumentError`. |
+| `require_scope` | `true` | Scoped host class queries raise `TypedEAV::ScopeRequired` when scope cannot be resolved. |
+| `versioning` | `false` | Boot-time master switch for transactional audit callbacks; host must also declare `versioned: true`. |
+| `actor_resolver` | `nil` | Optional callable supplying audit actor identity. Missing actor is allowed; applications can enforce stricter requirements in the resolver. |
+| `on_value_change` | `nil` | `->(value, change_type, context) { ... }`; after commit, with `:create`, `:update`, or `:destroy`. |
+| `on_field_change` | `nil` | `->(field, change_type) { ... }`; after commit, with `:create`, `:update`, `:destroy`, or `:rename`. |
+| `on_image_attached` | `nil` | `->(value, blob) { ... }`; image attachment notification after commit, when Active Storage is available. |
+
+Public callback errors are logged rather than propagated to the completed save.
+Versioning is independent of the public callback slots. Configure the versioning
+switch before the engine installs callbacks, not dynamically per request.
+See [events and versioning](../guides/events-and-versioning.md) for ordering,
+actor normalization, payloads, and audit transaction guarantees.
+
+## Field type registration
+
+```ruby
+TypedEAV.configure do |config|
+  config.register_field_type :phone, "MyApp::Fields::Phone"
+end
+```
+
+`config.field_types` maps type-name Symbols to class-name Strings;
+`config.type_names` lists registered names; `config.field_class_for(:phone)`
+constantizes a registered class and raises `ArgumentError` for an unknown type.
+Use registration to extend built-ins and the host macro's `types:` option to
+restrict a model. See [custom field types](../guides/fields.md).
+
+## Block-scoped state
+
+| API | Contract |
+| --- | --- |
+| `TypedEAV.with_scope(value) { ... }` | Temporary ambient scope; accepts a scalar, `[scope, parent_scope]`, or `nil`. Nested blocks restore prior state. |
+| `TypedEAV.current_scope` | Resolved normalized tuple, or `nil`; consults the block stack before the resolver. |
+| `TypedEAV.unscoped { ... }` | Explicit all-partition query mode; differs from `scope: nil` (global definitions only). |
+| `TypedEAV.unscoped?` | Whether that bypass is active. |
+| `TypedEAV.with_context(**kwargs) { ... }` | Temporary merged context for value events and versions; nested blocks restore prior state. |
+| `TypedEAV.current_context` | Frozen current context Hash, empty when unset. |
+
+Scope resolution is for field definitions. Continue to filter and authorize host
+records in the application. Scalar sorting and summaries reject all-partition
+mode because same-name definitions are ambiguous. See
+[scoping](../guides/scoping.md) and [queries](../guides/queries.md).

data/docs/reference/index.md

@@ -0,0 +1,16 @@
+---
+title: "Reference"
+---
+
+# Reference
+
+Use these pages to locate a method, check a default, or find its detailed guide.
+
+- [Public API](api.md): host records, queries, bulk operations, fields, schema/CSV, and partition helpers.
+- [Configuration](configuration.md): initializer settings, type registration, scope blocks, and event context.
+
+For an introduction, start with the [documentation home](../index.md). Reference
+entries describe application-facing contracts rather than every Ruby method in
+the implementation.
+
+- [Design decisions](../adr/index.md): the rationale behind user-facing behavior and extension choices.

data/lib/typed_eav/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TypedEAV
-  VERSION = "0.8.0"
+  VERSION = "0.8.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typed_eav
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - dchuk
@@ -55,6 +55,7 @@ files:
 - CHANGELOG.md
 - MIT-LICENSE
 - README.md
+- RELEASING.md
 - Rakefile
 - app/models/typed_eav/application_record.rb
 - app/models/typed_eav/field/base.rb
@@ -95,6 +96,38 @@ files:
 - db/migrate/20260507000000_add_label_to_typed_eav_fields.rb
 - db/migrate/20260712000000_enforce_parent_scope_invariant.rb
 - db/migrate/20260816000000_use_partial_covering_scalar_indexes.rb
+- docs/adr/0001-collapse-column-mapping-stack.md
+- docs/adr/0002-entity-query-orchestration.md
+- docs/adr/0003-keep-event-dispatcher-broker.md
+- docs/adr/0004-field-family-intermediate-bases.md
+- docs/adr/0005-keep-phase-six-modules-independent.md
+- docs/adr/0006-include-missing-via-set-complement.md
+- docs/adr/0007-visibility-versus-mutation-relations.md
+- docs/adr/0008-partial-covering-scalar-indexes.md
+- docs/adr/0009-string-search-indexing.md
+- docs/adr/0010-planner-statistics-policy.md
+- docs/adr/0011-multi-filter-query-strategy.md
+- docs/adr/0012-cross-scope-administrative-query-policy.md
+- docs/adr/0013-durable-versioning-and-field-deletion.md
+- docs/adr/index.md
+- docs/getting-started.md
+- docs/guides/architecture.md
+- docs/guides/bulk-operations.md
+- docs/guides/csv-import.md
+- docs/guides/development.md
+- docs/guides/events-and-versioning.md
+- docs/guides/fields.md
+- docs/guides/performance.md
+- docs/guides/queries.md
+- docs/guides/schema.md
+- docs/guides/scoping.md
+- docs/guides/upgrading.md
+- docs/guides/usage.md
+- docs/index.md
+- docs/maintaining.md
+- docs/reference/api.md
+- docs/reference/configuration.md
+- docs/reference/index.md
 - lib/generators/typed_eav/install/install_generator.rb
 - lib/generators/typed_eav/scaffold/scaffold_generator.rb
 - lib/generators/typed_eav/scaffold/templates/config/initializers/typed_eav.rb
@@ -178,6 +211,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/dchuk/typed_eav
   source_code_uri: https://github.com/dchuk/typed_eav
+  documentation_uri: https://dchuk.github.io/typed_eav/
   changelog_uri: https://github.com/dchuk/typed_eav/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/dchuk/typed_eav/issues
   allowed_push_host: https://rubygems.org