> For the complete documentation index, see [llms.txt](https://deadeyejoe.gitbook.io/fabrikk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://deadeyejoe.gitbook.io/fabrikk/reference/concepts.md). # Concepts ## What is an entity? This documentation makes heavy use of the word 'entity', but what is an entity? In general, entities are clojure **maps** that represent data in your application domain, e.g. a user with an id, name and email. Fabrikk also considers lists of entities to be entities in their own right, but this is generally an implementation detail. This documentation frequently references the following classes of entities: ### Primary Entity The entity that is currently being built, this term is generally only used when describing the build process. ### Dependent Entity Dependent entities are ones that are required to exist before the Primary entity can be built. There may be many such entities, and those entities may themselves have dependent entities. Dependent entities are specified using the `one` and `many` directives, and by passing the output of a `build` or `create` call as a value in a `with` build option. ### Referring Entity A referring entity is one that has dependent entities. It's generally used when talking about what happens when an entity is depended on. ## Templates A template is a collection of keywords and associated values that is used to generate an entity. The values in a template can be either constants, or directives. The simplest template is a map e.g.: ```clojure {:id (fab/sequence) :name "Jim Murphy" :email "Jim@example.com"} ``` However, in some cases the ordering of evaluation of values might be important, e.g. when using the `derive` directive. In this case, a template can be an ordered collection of maps and/or tuples, e.g. ```clojure [{:id (fab/sequence) :name "Jim Murphy"} [:email (fab/derive :id #(str "User-" % "@example.com")]] ``` The tuples here are equivalent to a map with a single key in it, either can be used. The order of evaluation is dictated by the list, and is undefined within maps. In practice, Clojure maps below 8 keys are usually array maps that have a defined order of iteration, but it's best not to rely on this. ### Compiled Template Templates can come from the following sources in order of precedence: * The main factory template * Trait templates (in the same order they're specified in [#build-options](#build-options "mention")) * `with` arguments in build-opts These templates are compiled into a single *Compiled template* before the entity is built. Compiled templates are built one template at a time, in the order of precedence, preserving the ordering of keys that are already in the compiled template. As a concrete example: ```clojure ;; These two templates [[[:one "one"] [:two "two"] [:three "three"]] [[:four "four"] [:two 2] [:one 1]]] ;; Are equivalent to this one after compilation [[:one 1] [:two 2] [:three "three"] [:four "four"]] ``` i.e. tuples in a compiled template can have their value overwritten, but their ordering is fixed once added. To build the entity, each key-value tuple is processed in order, the value is evaluated (processing any directives as necessary), and is then assoc'ed into the result map under the key. ## Build Options These functions accept build options to vary the entity being created: * `build` * `build-list` * `create` * `create-list` * `one` * `many` Build options have the following structure, all keys are optional:

Option	Description
`:with`	A template
:`traits`	A list of trait keywords, the corresponding templates will be compiled in the order they're referenced
`:without`	A list of keywords to be removed from the compiled template before the entity is built
`:associate-as`	A keyword or function. Allows you to control what value is associated when this entity is referenced by another. Accepts the special values `:itself` or `:identity`, which are equivalent to passing clojure.core/identity. See also #associating.
`:persist-with`	A keyword identifying a custom persistence method, allows you to override the configured default persistence method, does NOT change persistence for dependent entities, see Persistence

## Output Options These functions accept output options to vary the output from a factory: * `build` * `build-list` * `create` * `create-list` Output as options have the following structure, all keys are optional:

Option	Description
output-as	Keyword, override the default output format
transform	A function that transforms the entity to be output (only supported for some values of `output-as`)

The `output-as` option supports a wide variety of values:

Output Option	Supports transform	Description
`:meta`	false	Default. Outputs the primary entity with the build graph stored in metadata
:`value`	true	Outputs the primary entity only
`:context`	false	Outputs the build graph
`:tuple`	true	Outputs a 2 tuple of entity and build graph
`:grouped`	false	Outputs a map, with all dependent entities grouped by their factory id
`:build-order`	false	Outputs a list of entities in build order (reverse topological sort on the build graph)

## Build Graph This section gets into the weeds about the build graph that Fabrikk uses internally. Concepts here shouldn't be necessary for understanding the documentation, but may be useful for understanding the code. ### Basic Structure When you build an entity it forms a node in the build graph. When an entity depends on another entity, both entities are nodes in the build graph, and there is one edge between them for each key in the referring entity whose value depends on the dependent entity. Edges are labelled with the corresponding key, and the `:associate-as` value that is used to derive the value in the referring entity. As an example consider: ```clojure (def user (fab/->factory {:primary-key :id :template {:id (fab/sequence) :name "Alice"}})) (let [bob (fab/build user {:with {:name "Bob"}})] (fab/build user {:with {:parent bob :parent-name (fab/associate-as bob :name)}})) ;;=> {:id 2, :name "Alice", :parent 1, :parent-name "Bob"} ``` The build graph here has 2 nodes - users "Alice" and "Bob" - and 2 edges between those nodes. One edge is labelled `:parent` with `:associate-as` :id (the primary key of the user factory), and the other edge is labelled `:parent-name` with `:associate-as` :name. ### Associating When building a [#dependent-entity](#dependent-entity "mention"), the act of referencing it on the primary entity and inserting it into the build graph is referred to as '*Association**'***. More concretely, when an entity is associated: * A `key` is required, and an `:associate-as` option may be passed or inferred * If necessary the build graph of the dependent entity is merged into the build graph of the primary entity (only the first time this entity is associated) * An edge is created from the primary entity to the dependent entity. This edge is labelled with the `key` and `:associate-as` option * A value is derived from the dependent entity using `:associate-as`, and then assoc'ed into the primary entity under the `key` If no `:associate-as` option is provided, then the factory's `:primary-key` is used if present, otherwise the identity function is used (i.e. the full dependent entity is assoc'ed into the primary entity).