From 49a006dd18b17a422b48e812de5c9ffcc8e602dd Mon Sep 17 00:00:00 2001 From: Aaron Weiker Date: Fri, 1 May 2026 20:55:15 -0700 Subject: [PATCH] docs: add table of contents to all Ecto pattern files --- patterns/changesets.md | 13 +++++++++++++ patterns/multi.md | 10 ++++++++++ patterns/queries.md | 12 ++++++++++++ patterns/schemas.md | 11 +++++++++++ patterns/types.md | 9 +++++++++ 5 files changed, 55 insertions(+) diff --git a/patterns/changesets.md b/patterns/changesets.md index 4aba1d4..39fa227 100644 --- a/patterns/changesets.md +++ b/patterns/changesets.md @@ -2,6 +2,19 @@ Patterns extracted from Ecto's source code for building safe, composable data pipelines. +## Contents + +1. [`cast/4` — The External/Internal Data Boundary](#1-cast4--the-externalinternal-data-boundary) +2. [`change/2` — Internal-Only Modifications](#2-change2--internal-only-modifications) +3. [Validation Pipeline — Composable Validators](#3-validation-pipeline--composable-validators) +4. [`validate_change/3` — Custom Validators](#4-validate_change3--custom-validators) +5. [`add_error/4` — Manual Error Injection](#5-add_error4--manual-error-injection) +6. [`put_change/3` vs `force_change/3` — Tracked vs Forced Changes](#6-put_change3-vs-force_change3--tracked-vs-forced-changes) +7. [Constraints vs Validations — DB-level Safety](#7-constraints-vs-validations--db-level-safety) +8. [`prepare_changes/2` — Last-Mile DB-Aware Transforms](#8-prepare_changes2--last-mile-db-aware-transforms) +9. [`apply_action/2` — Schemaless Validation](#9-apply_action2--schemaless-validation) +10. [`cast_assoc/3` vs `put_assoc/4` — External vs Internal Association Changes](#10-cast_assoc3-vs-put_assoc4--external-vs-internal-association-changes) + --- ## 1. `cast/4` — The External/Internal Data Boundary diff --git a/patterns/multi.md b/patterns/multi.md index f9c9884..8f1532a 100644 --- a/patterns/multi.md +++ b/patterns/multi.md @@ -2,6 +2,16 @@ Patterns extracted from Ecto's `Ecto.Multi` source code. +## Contents + +1. [`Multi.new() |> Multi.insert/update/delete` — Named Operation Pipeline](#1-multinew--multiinsertupdatedelete--named-operation-pipeline) +2. [`Multi.run/3` — Arbitrary Code in a Transaction](#2-multirun3--arbitrary-code-in-a-transaction) +3. [Dependent Operations with Function Variants](#3-dependent-operations-with-function-variants) +4. [`Multi.merge/2` — Dynamic Transaction Composition](#4-multimerge2--dynamic-transaction-composition) +5. [`Multi.append/2` / `Multi.prepend/2` — Static Multi Composition](#5-multiappend2--multiprepend2--static-multi-composition) +6. [Tuple Keys — Dynamic Collections of Operations](#6-tuple-keys--dynamic-collections-of-operations) +7. [`Multi.to_list/1` — Testing Without a Database](#7-multito_list1--testing-without-a-database) + --- ## 1. `Multi.new() |> Multi.insert/update/delete` — Named Operation Pipeline diff --git a/patterns/queries.md b/patterns/queries.md index 1649bc4..b2d465b 100644 --- a/patterns/queries.md +++ b/patterns/queries.md @@ -2,6 +2,18 @@ Patterns extracted from Ecto's query layer source code. +## Contents + +1. [Named Query Functions — Composable Query Building](#1-named-query-functions--composable-query-building) +2. [Query Piping — Schema to Query Pipeline](#2-query-piping--schema-to-query-pipeline) +3. [Named Bindings — Position-Independent Composition](#3-named-bindings--position-independent-composition) +4. [`dynamic/2` — Runtime-Constructed Predicates](#4-dynamic2--runtime-constructed-predicates) +5. [`subquery/1` — Correlated Subqueries](#5-subquery1--correlated-subqueries) +6. [`exclude/2` — Strip Clauses for Reuse](#6-exclude2--strip-clauses-for-reuse) +7. [Bindingless Queries — Data-Driven Clauses](#7-bindingless-queries--data-driven-clauses) +8. [`select_merge/3` — Augmenting Selects Dynamically](#8-select_merge3--augmenting-selects-dynamically) +9. [`fragment/1` and `type/2` — Escape Hatches for DB-Specific Expressions](#9-fragment1-and-type2--escape-hatches-for-db-specific-expressions) + --- ## 1. Named Query Functions — Composable Query Building diff --git a/patterns/schemas.md b/patterns/schemas.md index a272fd6..6d382fb 100644 --- a/patterns/schemas.md +++ b/patterns/schemas.md @@ -2,6 +2,17 @@ Patterns extracted from `lib/ecto/schema.ex` in the Ecto source. +## Contents + +1. [Base Schema Module — App-Wide Schema Defaults](#1-base-schema-module--app-wide-schema-defaults) +2. [`@primary_key false` — Composite or No Primary Key](#2-primary_key-false--composite-or-no-primary-key) +3. [Virtual Fields — In-Memory-Only Data](#3-virtual-fields--in-memory-only-data) +4. [`embedded_schema/1` — Schemaless Validation Structs](#4-embedded_schema1--schemaless-validation-structs) +5. [`@timestamps_opts` — Consistent Timestamp Types](#5-timestamps_opts--consistent-timestamp-types) +6. [Field `:source` Option — Column Name Mapping](#6-field-source-option--column-name-mapping) +7. [`redact: true` — Protecting Sensitive Fields](#7-redact-true--protecting-sensitive-fields) +8. [`__schema__/1` Reflection — Runtime Schema Introspection](#8-__schema__1-reflection--runtime-schema-introspection) + --- ## 1. Base Schema Module — App-Wide Schema Defaults diff --git a/patterns/types.md b/patterns/types.md index 98f5003..55370ca 100644 --- a/patterns/types.md +++ b/patterns/types.md @@ -2,6 +2,15 @@ Patterns extracted from Ecto's type system source code. +## Contents + +1. [`use Ecto.Type` — The Four-Callback Custom Type](#1-use-ectotype--the-four-callback-custom-type) +2. [`embed_as/1` — Controlling Embedded Serialization](#2-embed_as1--controlling-embedded-serialization) +3. [`equal?/2` — Custom Equality for Change Detection](#3-equal2--custom-equality-for-change-detection) +4. [`Ecto.Enum` — Constrained Atom Fields](#4-ectoenum--constrained-atom-fields) +5. [`Ecto.ParameterizedType` — Types with Options](#5-ectoparameterizedtype--types-with-options) +6. [Schemaless Types — `{data, types}` Changesets](#6-schemaless-types--data-types-changesets) + --- ## 1. `use Ecto.Type` — The Four-Callback Custom Type