Graphden documentation

Lesson 01 — Anatomy of a fn-def

Goal: by the end of this lesson you can write a fn-def by hand and explain each part of it.

Concepts introduced: fn-def, :name, :parent, :args, base function, fns.edn.

A fn-def is the source declaration of a graph function: a stored computation identified by an ID, with a name within a namespace. An argument slot identifies one named, typed input; a binding supplies that input for a function. See slots and bindings. A type describes allowed values. Types also use function rows, but have no executable implementation; Lesson 08 explains that role.

The smallest meaningful fn-def

{:name :hello-handler
 :parent :const
 :args  {:value {:status 200 :body "Hello from Graphden!"}}}

That’s a complete fn-def. Three keys:

Executing :hello-handler returns the map {:status 200 :body "Hello from Graphden!"}.

Where fn-defs live

Two places:

  1. resources/packages/<pkg>/<module>/fns.edn — a module map with :namespace and a :fns vector of definitions, loaded at startup. This is the package source form. See PACKAGES.md.
  2. Inside the running editor — when you click + in a namespace, the editor creates a fn entity directly via POST /api/entities/fn. The editor writes entity fields and bindings; the package loader translates source keys such as :parent and :args into those stored entities. The source map is not that endpoint’s request shape.

For this lesson assume you’re typing into the editor. The fns.edn form is what you’d write for code review.

Two kinds of fn

Look at the :parent field. There are two kinds of executable fn you can parent to (type rows can also contribute argument structure; see Lesson 08):

Kind What it is Example How to spot one
Base function A focused native implementation :const, :add, :render-hiccup, :pg-query Has a :return-type-fn-id, no :parent-ids
fn-def A graph composition using parents and bindings :hello-handler, :web-server, :get-route Has at least one :parent-ids

You can parent a new fn-def to either kind. Inheritance works the same way for both.

A fn-def that uses a fn-def

Now let’s compose two:

{:name :hello-handler
 :parent :const
 :args  {:value {:status 200 :body "Hello!"}}}

{:name :hello-route
 :parent :assoc
 :args  {:map {} :key "handler" :value :hello-handler}}

:hello-route parents to :assoc — a base function that returns {key value} merged into map. The interesting part: :value is bound to :hello-handler (the keyword form of its name). When :hello-route runs:

  1. The executor sees the ref :hello-handler in slot :value.
  2. It looks at :assoc’s slot type for :value — not :fn-typed.
  3. So it executes :hello-handler (gets the response map) and uses that as the value of :value.

The same syntax in a :fn-typed slot would behave differently — the executor prepares a callable for the parent to invoke. If the reference returns a callable, the executor first evaluates that constructor. Lesson 09 explains both cases.

Try it

Prefer to be shown? This lesson exists as a guided in-editor tour: open the demo with the tour running (no sign-up), or pick “Interactive tutorial” in the editor’s account menu.

In the running editor:

  1. At the bottom of the Explorer click New namespace, type tutorial and press Enter.
  2. Expand the tutorial row, hover it and click its +. Choose New graph…, type one-plus-one and press Enter. The new fn opens on the canvas.
  3. On the card click set parent…, type add in the picker and pick core.arithmetic.add — the primitive that sums the numbers in its :nums list. Inheriting it exposes :nums as a + placeholder.
  4. :nums is a LIST, so the + offers Append literal rather than a single value: append 1, Save. Look at the edge now: one :nums label, and after its type chip the line fans out — a branch to the 1 and a branch to a fresh +, the list’s next free slot (a plain argument splits off before its chip; a list element after it). Click that + and append a second 1. The card now reads 1, 1 — the whole input of your function, as data on the card. (In fns.edn you’d write :args {:nums [1 1]}.)
  5. Click the ⋯ button on the card’s top row, then ▶ Run, then Run in the Run pane that opens in the right panel: 2. Nothing was built or deployed — the card IS the program, the pane is its output. Change a number and run again; the answer follows.

The value form takes JSON: a map, a bare number, or plain text. When the slot’s type is already known it renders one field per key instead, and its {} raw button switches back to the raw editor.

What we glossed over

Each of these is built on the same fn-def shape; we just keep peeling layers.

Next

Lesson 02 — Reading a card