#lang scribble/lp2
@(require "../lib/doc.rkt")
@doc-lib-setup

@title[#:style manual-doc-style]{Graph library}

@(table-of-contents)

@; TODO: allow a mapping to return a new placeholder, in order to act as a
@; redirect. All references to the old placeholder will act as if they were to
@; the new placeholder.

@section{Introduction}

This module provides a @tc[graph] macro which helps constructing immutable
graphs (using lambdas to defer potentially cyclic references).

@subsection{Example usage}

We will start with a running example, which will help us both show the macro's
syntax, and see some of the key advantages offered by this graph library.

@subsection{The graph's type}

Each node type in the graph is a variant's constructor, tagged with the node
name. For example, a graph representing a city and its inhabitants could use
these constructors:

@chunk[<example-variants>
       [City [streets : (Listof Street)] [people : (Listof Person)] <m-city>]
       [Street [sname : String] [houses : (Listof House)] <m-street>]
       [House [owner : Person] [location : Street] <m-house>]
       [Person [name : String] <m-person>]]

Notice the cycle in the type: a street contains houses, which are located on the
same street.

@subsubsection{A seed from which to grow the graph: the root parameters}

In order to build a graph with that type, we start from the root parameters.
Here, we will take a representation of the city as a list of
@tc[(street-name . person-name)] pairs, and will convert it to a more convenient
graph representation. Our single root parameter will thus be the whole list:

@chunk[<example-root>
       '(["Amy" . "Ada Street"]
         ["Jack" . "J Street"]
         ["Anabella" . "Ada Street"])]

We will then provide a mapping from the root parameter to the root node, in our
case @tc[City]. When processing the root parameter, one can call other mappings
that will create their corresponding nodes.

@subsubsection{Mapping the root parameters to the root node}

Here is the root mapping for our example. It maps over the list of names and
street names @tc[c], and calls for each element the @tc[m-street] and
@tc[m-person] mappings.

@; Would be nicer with (map (∘ (curry street c) car) c)), but that doesn't
@; typecheck (yet).
@chunk[<m-city>
       [(m-city [c : (Listof (Pairof String String))])
        (City (remove-duplicates (map (curry m-street c) (cdrs c)))
              (remove-duplicates (map m-person (cars c))))]]

@subsubsection{More mappings}

Next, we write the @tc[m-street] mapping, which takes a street name and the
whole city @tc[c] in list form, and creates a @tc[Street] node.

@chunk[<m-street>
       [(m-street [c : (Listof (Pairof String String))] [s : String])
        (Street s (map (curry (curry m-house s) c)
                       (cars (filter (λ ([x : (Pairof String String)])
                                       (equal? (cdr x) s))
                                     c))))]]

The @tc[m-house] mapping defined below calls back the @tc[m-street] mapping, to
store for each house a reference to the containing street. Normally, this would
cause infinite recursion in an eager language, like @tc[typed/racket]. However,
the mappings aren't called directly, and instead, in the body of @tc[m-house],
@tc[m-street] is shadowed by a function which returns a placeholder. This allows
us to not worry about mutually recursive mappings: a mapping can be called any
number of times with the same data, it will actually only be run once.

The @tc[define-graph] macro will post-process the result of each mapping, and
replace the placeholders with promises for the the result of the mapping. The
promises are not available during graph construction, so there is no risk of
forcing one before it is available.

We can now write the @tc[m-house] and @tc[m-person] mappings.

@chunk[<m-house>
       [(m-house [s : String]
                 [c : (Listof (Pairof String String))]
                 [p : String])
        (House (m-person p) (m-street c s))]]

@chunk[<m-person>
       [(m-person [p : String])
        (Person p)]]

@subsubsection{Creating an instance of the graph}

For now, we will supply directly the root arguments to the @tc[define-graph]
macro, as well as the node types and mappings. We can later curry the macro, so
that it first takes the node types and mappings, and produces a lambda taking
the root arguments as parameters.

@chunk[<use-example>
       (define-graph gr <example-variants>)
       (define g1 (gr <example-root>))
       (define g g1)]

@subsection{More details on the semantics}

Let's take a second look at the root mapping:

@chunk[<m-city-2>
       [(m-city [c : (Listof (Pairof String String))])
        (City (remove-duplicates (map (curry m-street c) (cars c)))
              (remove-duplicates (map m-person (cdrs c))))]]

As this example shows, we can use @tc[m-street] as any other function, passing
it to @tc[curry], and calling @tc[remove-duplicates] on the results. Note that
each placeholder returned by @tc[m-street] will contain all information passed
to it, here a street name and @tc[c]. Two placeholders for @tc[m-street] will
therefore be @tc[equal?] if and only if all the arguments passed to
@tc[m-street] are @tc[equal?]. The placeholders also include a symbol specifying
which mapping was called, so two placeholders for two different mappings will
not be @tc[equal?], even if identical parameters were supplied.

The node type allowing placeholders is derived from the ideal type given above.
Here, the type for @tc[Person] is @tc[[Person [name : String]]], so there are no
substitutions to make. Conversely, the type for @tc[City], originally expressed
as @tc[[(Listof Street) (Listof Person)]], will be rewritten as
@tc[[(Listof Street/placeholder-type) (Listof Person/placeholder-type)]].

The @tc[rewrite-type] module, which we use to derive types with placeholders
from the ideal ones, only handles a handful of the types offered by
@tc[typed/racket]. In particular, it does not handle recursive types described
with @tc[Rec] yet.

@section{Implementation}

In this section, we will describe how the @tc[define-graph] macro is
implemented.

@subsection{The macro's syntax}

We use a simple syntax for @tc[define-graph], and will later make it more
flexible through wrapper macros.

@chunk[<signature>
       (define-graph . (~and main-args <main-macro-arguments>))]
@chunk[<main-macro-arguments>
       (name (~optional (~and debug #:debug))
             (~maybe #:definitions (extra-definition:expr …))
             [node <field-signature> … <mapping-declaration>]
             …)]

Where @tc[<field-signature>] is:

@chunk[<field-signature>
       [field:id :colon field-type:expr]]

And @tc[<mapping-declaration>] is:

@chunk[<mapping-declaration>
       ((mapping:id [param:id :colon param-type:expr] …)
        . mapping-body)]

@subsection{The different types of a node}

A single node name can refer to several types:

@itemlist[
 @item{The @emph{ideal} type, expressed by the user, for example
  @racket[[City (Listof Street) (Listof Person)]], it is never used as-is in
  practice}
 @item{The @emph{placeholder} type, type and constructor, which just store the
  arguments for the mapping along with a tag indicating the node name}
 @item{The @emph{incomplete} type, in which references to other node types are
  allowed to be either actual (@racket[incomplete]) instances, or placeholders.
  For example, @racket[[City (Listof (U Street Street/placeholder-type))
                        (Listof (U Person Person/placeholder-type))]].}
 @item{The @emph{with-indices} type, in which references to other node types
  must be replaced by an index into the results list for the target node's
  @racket[with-promises] type. For example,
  @racket[[City (Listof Street/index-type)
           (Listof Person/index-type)]].}
 @item{The @emph{with-promises} type, in which references to other node types
  must be replaced by a @racket[Promise] for the target node's
  @racket[with-promises] type. For example,
  @racket[[City (Listof (Promise Street/with-promises-type))
           (Listof (Promise Person/with-promises-type))]].}
 @item{The @emph{mapping function}, which takes some parameters and
  returns a node (using the code provided by the user)}]

We derive identifiers for these based on the @tc[node] name:

@chunk[<define-ids/first-step>
       (define-temp-ids "~a/constructor" (node …) #:first-base root)
       
       (define-temp-ids "~a/make-placeholder" (node …))
       (define-temp-ids "~a/make-placeholder-type" (node …))
       (define-temp-ids "~a/placeholder-struct" (node …))
       (define-temp-ids "~a/placeholder-type" (node …))
       
       (define-temp-ids "~a/incomplete-type" (node …))
       (define-temp-ids "~a/make-incomplete" (node …))
       (define-temp-ids "~a/make-incomplete-type" (node …))
       (define-temp-ids "~a/incomplete-tag" (node …))
       (define-temp-ids "~a/incomplete-type" ((field …) …))
       
       (define-temp-ids "~a/with-promises-type" (node …) #:first-base root)
       
       (define-temp-ids "~a/index-type" (node …))]

@chunk[<pass-to-second-step>
       (node/constructor …)
       root/constructor
       
       (node/make-placeholder …)
       (node/make-placeholder-type …)
       (node/placeholder-struct …)
       (node/placeholder-type …)
       
       (node/incomplete-type …)
       (node/make-incomplete …)
       (node/make-incomplete-type …)
       (node/incomplete-tag …)
       ((field/incomplete-type …) …)
       
       (node/with-promises-type …)
       root/with-promises-type
       
       (node/index-type …)]

@chunk[<define-ids/second-step>
       (define/with-syntax ((root-param …) . _) #'((param …) …))
       (define/with-syntax ((root-param-type …) . _) #'((param-type …) …))
       (define-temp-ids "~a/main-constructor" name)
       
       (define-temp-ids "~a/placeholder-queue" (node …))
       
       (define-temp-ids "~a/with-indices-type" (node …))
       (define-temp-ids "~a/make-with-indices" (node …))
       (define-temp-ids "~a/with-indices-tag" (node …))
       (define-temp-ids "~a/with-indices→with-promises" (node …)
         #:first-base root)
       
       (define-temp-ids "~a/make-with-promises" (node …))
       (define-temp-ids "~a/with-promises-tag" (node …))
       
       (define-temp-ids "~a/mapping-function" (node …))
       (define-temp-ids "~a/mapping-function-type" (node …))
       
       (define-temp-ids "~a/database" (node …) #:first-base root)
       
       (define-temp-ids "~a/value" ((field …) …))]

@subsection{A versatile identifier: the graph's name}

@; TODO: only accept the syntax #:λroot, and provide the rest in wrapper macros.

The graph name will be used in several ways:

@itemlist[
 @item{As the constructor for the root node, or another node. We allow both
  invoking the constructor directly, or get the first-class procedure. Wrapper
  macros will allow the syntax @racket[g.node] (and @racket[.g.node]) to refer
  to the constructor for @racket[node].}
 @item{As a type expander, to refer to the type of the nodes when outside the
  @; TODO: secref
  graph declaration. Wrapper macros will allow the syntax @racket[g.node] to
  refer to @racket[node]'s type.}
 @; TODO: @item{As a match expander}
 ]

@chunk[<define-multi-id>
       (define-multi-id name
         #:type-expander <graph-type-expander>
         #:call (λ (stx)
                  (syntax-parse stx
                    ;; TODO: move this to a dot expander, so that writing
                    ;; g.a gives a constructor for the a node of g, and
                    ;; (g.a foo bar) or (let ((c .g.a)) (c foo bar)) both
                    ;; call it
                    [(_ #:λroot (~datum node))
                     #'node/constructor]
                    …
                    [(_ #:root (~datum node) . rest)
                     (syntax/loc stx (node/constructor . rest))]
                    …
                    [(_ . rest)
                     (syntax/loc stx (root/constructor . rest))]))
         #:id (λ (stx) #'root/constructor))]

@subsection{Overview}

The macro relies heavily on two sidekick modules: @tc[rewrite-type], and
@tc[fold-queue]. The former will allow us to derive from the ideal type of a
node the incomplete type and the with-promises type. It will also allow us to
search inside instances of incomplete nodes, in order to extract the
placehoders, and replace these parts with promises. The latter, @tc[fold-queue],
will be used to process all the pending placeholders, with the possibility to
enqueue more as new placeholders are discovered inside incomplete nodes.

Our macro allows extra user-provided definitions (provided using the
@tc[#:definitions] keyword). These definitons should have access to the
identifiers for node constructors and mapping functions. However, these
definitions may introduce macros (such as type-expanders) which must be made
available to the mapping and node declarations. More specifically, our macro
will run @tc[expand-type] on the fields' types, and should expand any
type-expanders introduced by the extra user-provided definitions.

To solve this chicken-and-egg problem, we use two steps: first we generate just
enough code so that we can inject the extra user definitions. Then we call a
second macro, which does the real work. When expanded, the second macro will
have the extra user-provided definitions in its scope.

@subsubsection{First step}

The first step first introduce a few stubs using generated names, which won't be
available outside the graph definition:

@chunk[<first-step-definitions>
       <define-multi-id>
       
       (begin <define-make-placeholder/first-step>) …
       (begin <define-make-incomplete/first-step>) …
       ;; TODO: Struct definitions have to be outside due to TR bug #192
       ;; https://github.com/racket/typed-racket/issues/192
       (begin <define-placeholder-struct/first-step>) …
       (begin <define-index-struct/first-step>) …]

It will then bind these generated names to identifiers which can be used in the
scope of the graph declaration. There, we will first inject the user-supplied
extra definitions, and a call to the second step macro:

@chunk[<first-step-bindings>
       (splicing-let ([mapping node/make-placeholder]
                      …
                      [node node/make-incomplete]
                      …)
         (?? (begin extra-definition …))
         <call-second-step>)]

The first step macro is defined as follows:

@chunk[<first-step>
       (define-syntax/parse <signature>
         <define-ids/first-step>
         (template/debug debug
           ;; Can't use (let () …) because of TR bug #262
           ;; https://github.com/racket/typed-racket/issues/262
           (begin
             <first-step-definitions>
             <first-step-bindings>)))]

@subsubsection{Second step}

The second step will take a few extra arguments, to keep knowledge of the
identifiers defined in the first step:

@chunk[<signature-second-step>
       (define-graph-second-step [<pass-to-second-step>]
         <main-macro-arguments>)]

It will be called from the first step with the following syntax:

@chunk[<call-second-step>
       (define-graph-second-step [<pass-to-second-step>]
         main-args)]

@chunk[<second-step>
       (define-syntax/parse <signature-second-step>
         <define-ids/second-step>
         (template/debug debug
          (begin
            (begin <define-mapping-function>) …
            
            (begin <define-placeholder-type>) …
            (begin <define-make-placeholder-type>) …
            (begin <define-with-indices>) …
            (begin <define-with-promises>) …
            (begin (begin <define-field/incomplete-type>) …) …
            (begin <define-incomplete-type>) …
            
            (begin <define-mapping-function-type>) …
            
            (: fq (case→ (→ 'node/placeholder-queue node/placeholder-type
                            (List (Vectorof node/with-indices-type) …))
                         …))
            (define (fq queue-name placeholder)
              <fold-queues>)
            
            <constructors>)))]

We shall define a graph constructor for each node type, which accepts the
arguments for that node's mapping, and generates a graph rooted in the resulting
node.

@chunk[<constructors>
       (begin
         (: node/constructor (→ param-type … (Promise node/with-promises-type)))
         (define (node/constructor param …)
           (match-let ([(list node/database …)
                        (fq 'node/placeholder-queue
                            (node/make-placeholder param …))])
             (begin <define-with-indices→with-promises>) …
             (delay (node/with-indices→with-promises
                     (vector-ref node/database 0))))))
       …]


@section{Injecting the first placeholder in the queue}

When the graph constructor is called with the arguments for the root parameters,
it is equivalent to make and then resolve an initial placeholder. We will use a
function from the @tc[fold-queue] library to process the queues of pending
placeholders, starting with a queue containing only that root placeholder.
We will have one queue for each placeholder type.@note{It we had only one queue,
 we would have only one collection of results, and would need a @racket[cast]
 when extracting nodes from the collection of results.} The element types of the
queues will therefore be these placeholder types.

@chunk[<fold-queue-type-element>
       node/placeholder-type]

The return type for each queue will be the corresponding with-indices type. The
fold-queues function will therefore return a vector of with-indices nodes for
each node type.

@chunk[<fold-queue-type-result>
       node/with-indices-type]


@; Problem: how do we ensure we return the right type for the root?
@; How do we avoid casts when doing look-ups?
@; We need several queues, handled in parallel, with distinct element types.
@; * Several result aggregators, one for each type, so we don't have to cast
@; * Several queues, so that we can make sure the root node is of the expected
@;   type.

@; TODO: clarity.
@; The @tc[fold-queues] function allows us to associate each element with a tag,
@; so that, inside the processing function and outside, we can refer to an
@; element using this tag, which can be more lightweight than keeping a copy of
@; the element.
@; 
@; We will tag our elements with an @tc[Index], which prevents memory leakage:
@; if we kept references to the original data added to the queue, a graph's
@; representation would hold references to its input, which is not the case when
@; using simple integers to refer to other nodes, instead of using the input for
@; these nodes. Also, it makes lookups in the database much faster, as we will
@; be able to use an array instead of a hash table.

@subsection{The queues of placeholders}

The fold-queues macro takes a root element, in our case the root placeholder,
which it will insert into the first queue. The next clauses are the queue
handlers, which look like function definitions of the form
@tc[(queue-name [element : element-type] Δ-queues enqueue) : result-type]. The
@tc[enqueue] argument is a function used to enqueue elements and get a tag in
return, which can later be used to retrieve the processed element.

Since the @tc[enqueue] function is pure, it takes a parameter of the same type
as @tc[Δ-queues] representing the already-enqueued elements, and returns a
modified copy, in addition to the tag. The queue's processing body should return
two values: the result of processing the element, and the latest version of
@tc[Δ-queues], which stores the new elements to be added to the queue.

@chunk[<fold-queues>
       (fold-queues #:root queue-name
                    placeholder
                    [(node/placeholder-queue [e : <fold-queue-type-element>]
                                             [Δ-queues : Δ-Queues]
                                             enqueue)
                     : <fold-queue-type-result>
                     <fold-queue-body>]
                    ...)]

@subsection{Making placeholders for nodes}

We start creating the root placeholder which we provide to @tc[fold-queues].

@; TODO: this is wrong, since we now have a constructor for each node type.
@chunk[<root-placeholder>
       (node/make-placeholder root-param …)]

To make the placeholder, we will need a @tc[node/make-placeholder] function for
each @tc[node]. We first define the type of each placeholder (a list of
arguments, tagged with the @tc[node]'s name):

@; TODO: maybe replace node types with placeholder types

@chunk[<define-placeholder-struct/first-step>
       (struct (A) node/placeholder-struct ([f : A]) #:transparent)]
@chunk[<define-placeholder-type>
       (define-type node/placeholder-type
         (node/placeholder-struct (List param-type …)))]

@; TODO: just use (variant [mapping param-type ...] ...)

Then we define the @tc[node/make-placeholder] function:

@chunk[<define-make-placeholder-type>
       (define-type node/make-placeholder-type
         (→ param-type … node/placeholder-type))]
@chunk[<define-make-placeholder/first-step>
       (: node/make-placeholder node/make-placeholder-type)
       (define (node/make-placeholder param …)
         (node/placeholder-struct (list param …)))]

@subsection{Making with-indices nodes}

We derive the @tc[with-indices] type from each @emph{ideal} node type using the
@tc[tmpl-replace-in-type] template metafunction from the rewrite-type library.
We replace all occurrences of a @tc[node] name with an @tc[Index], which
indicates at which index in the queue's results the successor can be found.

@; TODO: use a type-expander here, instead of a template metafunction.

@chunk[<define-index-struct/first-step>
       (struct node/index-type ([i : Index]) #:transparent)]

@chunk[<define-with-indices>
       (define-type node/with-indices-type
         (List 'node/with-indices-tag <field/with-indices-type> …))
       
       (: node/make-with-indices (→ <field/with-indices-type> …
                                    node/with-indices-type))
       (define (node/make-with-indices field …)
         (list 'node/with-indices-tag field …))]

@chunk[<field/with-indices-type>
       (tmpl-replace-in-type field-type [node node/index-type] …)]

@subsection{Making with-promises nodes}

We derive the @tc[with-promises] type from each @emph{ideal} node type using
the @tc[tmpl-replace-in-type] template metafunction from the rewrite-type
library. We replace all occurrences of a @tc[node] name with a @tc[Promise] for
that node's @tc[with-promises] type.

@; TODO: use a type-expander here, instead of a template metafunction.

@CHUNK[<define-with-promises>
       (define-type node/with-promises-type
         (tagged node/with-promises-tag
                 [field : <field/with-promises-type>] …))
       
       (: node/make-with-promises (→ <field/with-promises-type> …
                                     node/with-promises-type))
       (define (node/make-with-promises field/value …)
         (tagged node/with-promises-tag
                 [field : <field/with-promises-type> field/value]
                 …))]

@CHUNK[<field/with-promises-type>
       (tmpl-replace-in-type field-type
                             [node (Promise node/with-promises-type)] …)]

@subsection{Making incomplete nodes}

We derive the @tc[incomplete] type from each @emph{ideal} node type using
the @tc[tmpl-replace-in-type] template metafunction from the rewrite-type
library. We replace all occurrences of a @tc[node] name with its
@tc[placeholder] type.

@; TODO: use a type-expander here, instead of a template metafunction.

@chunk[<define-incomplete-type>
       (define-type node/incomplete-type
         (List 'node/incomplete-tag field/incomplete-type …))
       
       (define-type node/make-incomplete-type
         (→ field/incomplete-type … node/incomplete-type))]
@chunk[<define-make-incomplete/first-step>
       (: node/make-incomplete node/make-incomplete-type)
       (define (node/make-incomplete field …)
         (list 'node/incomplete-tag field …))]

@chunk[<define-field/incomplete-type>
       (define-type field/incomplete-type <field/incomplete-type>)]
@chunk[<field/incomplete-type>
       (tmpl-replace-in-type field-type
                             [node node/placeholder-type] …)]

@subsection{Converting incomplete nodes to with-indices ones}

@; TODO: we don't need that many annotations
@chunk[<placeholder→with-indices-function>
       (λ ([p : node/placeholder-type] [Δ-acc : Δ-Queues])
         : (values node/index-type Δ-Queues)
         (% index new-Δ-acc = (enqueue 'node/placeholder-queue p Δ-acc)
            (values (node/index-type index)
                    new-Δ-acc)))]

@chunk[<placeholder→with-indices-clause>
       [node/placeholder-type
        node/index-type
        (struct-predicate node/placeholder-struct)
        <placeholder→with-indices-function>]]

@subsubsection{Processing the placeholders}

@; TODO: also allow returning a placeholder (which means we should then
@; process that placeholder in turn). The placeholder should return the
@; same node type, but can use a different mapping?
@; Or maybe we can do this from the ouside, using a wrapper macro?

@; TODO: we don't need that many let etc., use % instead once everything works.
@CHUNK[<fold-queue-body>
       (let ([mapping-result
              (apply node/mapping-function
                     ((struct-accessor node/placeholder-struct 0) e))]
             [f (tmpl-fold-instance (List <field/incomplete-type> …)
                                    Δ-Queues
                                    <placeholder→with-indices-clause> …)])
         (let-values ([(r new-Δ-queues) (f (cdr mapping-result) Δ-queues)])
           (values (apply node/make-with-indices r)
                   new-Δ-queues)))]

Where @tc[<field-incomplete-type>] is the @tc[field-type] in which node types
are replaced by placeholder types, as defined earlier.

@subsection{The mapping functions}

We define the mapping functions as they are described by the user, with an
important change: Instead of returning an @emph{ideal} node type, we expect them
to return an @emph{incomplete} node type.

@chunk[<define-mapping-function>
       (: node/mapping-function node/mapping-function-type)
       (define node/mapping-function
         (ann (λ (param …) . mapping-body)
              node/mapping-function-type))]

@chunk[<define-mapping-function-type>
       (define-type node/mapping-function-type
         (→ param-type … node/incomplete-type))]

@subsection{Returning a with-promises nodes}

We will return a with-promises version of the root node, which contains promises
for its successors. The user can then force one of these to obtain the
with-promises version of the desired successor.

@; TODO: put a diagram here, or an example at least

This use of promises is safe, since their resolution depends only on the vectors
returned by fold-queues, which are already fully computed when we create the
root with-promises node. We therefore have no risk of forcing a promise that
can't be resolved, or that would depend on itself, causing an infinite loop.

@subsubsection{Why use promises?}

We use promises because we would like to only use immutable data structures.
Resolving the links in the graph would require mutating the nodes, so instead,
when extracting the @emph{placeholders} from an @emph{incomplete} node, we
produce a @emph{with-indices} node, which, instead of direct references to the
successors, just stores a tag and index. Later, the successors are processed,
and stored at the corresponding index in the queue for that tag.

We then wrap each tagged index with a lambda, which also holds a reference to
the vectors returned by fold-queue, which containin all the with-indices nodes.
When calling the lambda, it extracts the with-indices node for that tag and
index, further replaces the tagged indices within, and returns a brand new
with-promises node.

We could leave it as that, having the with-promises nodes contain lambdas
instead of actual references to their successors. However, when an immutable
function (like one of these lambdas) is called twice with the same arguments (in
this case none), @tc[typed/racket]'s occurrence typing currently does not infer
that the result will always be the same. This means that pattern-matching using
the @tc[match] macro won't work properly, for example. We therefore wrap these
functions into promises. The occcurrence typing mechanism in @tc[typed/racket]
knows that a promise will always return the same value when forced multiple
times. By default, promises use mutable data structures under the hood, to cache
their result, but we do not rely on that. We could use @tc[delay/name], which
doesn't cache the return value, but it was removed from @tc[typed/racket]
because @hyperlink["https://github.com/racket/typed-racket/issues/159"]{it
 caused type safety problems}.

@subsubsection{Creating with-promises nodes from with-indices ones}

@chunk[<index→promise-clause>
       [node/index-type
        (Promise node/with-promises-type)
        (struct-predicate node/index-type)
        (λ ([tagged-index : node/index-type] [acc : Void])
          : (values (Promise node/with-promises-type) Void)
          (values <index→promise> acc))]]

TODO: check what we are closing over in that promise.
I think we are closing over the successor-with-index (but not its whole
database), as well as everything that the with-indices→with-promises function
closes over.

@chunk[<index→promise>
       (let ([successor-with-index
              (vector-ref node/database ((struct-accessor node/index-type 0)
                                         tagged-index))])
         (delay (node/with-indices→with-promises successor-with-index)))]

@chunk[<define-with-indices→with-promises>
       (: node/with-indices→with-promises (→ node/with-indices-type
                                             node/with-promises-type))
       (define (node/with-indices→with-promises n)
         (define f (tmpl-fold-instance (List <field/with-indices-type> …)
                                       Void
                                       <index→promise-clause> …))
         (apply node/make-with-promises (first-value (f (cdr n) (void)))))]

Where @tc[<field-with-indices-type>] is the @tc[field-type] in which node types
are replaced by tagged indices, as defined earlier.

@;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

@section{Referencing the type of nodes}

The identifier defined by @tc[define-graph] will both act as a constuctor for
graph instances, and as a type-expander, that we will use to reference the node
types. We will thus be able to refer to the type of Street nodes in our example
via @tc[(g Street)].

@chunk[<graph-type-expander>
       (λ (stx)
         (syntax-parse stx
           [(_ (~datum node)) #'node/with-promises-type] …
           [(_ #:incomplete (~datum node)) #'node/incomplete-type] …
           [(_ #:make-incomplete (~datum node))
            #'(→ field/incomplete-type … node/incomplete-type)] …
           [(_ #:incomplete (~datum node) fld)
            (syntax-parse #'fld
              [(~datum field) #'field/incomplete-type] …)] …
           [(_ #:make-placeholder (~datum node))
            #'node/make-placeholder-type] …
           [(_ #:placeholder (~datum node)) #'node/placeholder-type] …))]

We will be able to use this type expander in function types, for example:

@chunk[<type-example>
       (define (type-example [x : (gr Street)])
         : (gr Street)
         x)
       (check-equal?: (let* ([v1 (car (structure-get (cadr (force g)) streets))]
                             [v2 (ann (type-example (force v1)) (gr Street))]
                             [v3 (structure-get (cadr v2) sname)])
                        v3)
                      : String
                      "Ada Street")]

@section{Putting it all together}

@chunk[<module-main>
       (module main typed/racket
         (require (for-syntax syntax/parse
                              racket/syntax
                              syntax/stx
                              syntax/parse/experimental/template
                              racket/sequence
                              racket/pretty
                              "rewrite-type.lp2.rkt"
                              "../lib/low-untyped.rkt"
                              "meta-struct.rkt")
                  racket/splicing
                  "fold-queues.lp2.rkt"
                  "rewrite-type.lp2.rkt"
                  "../lib/low.rkt"
                  "structure.lp2.rkt"
                  "variant.lp2.rkt"
                  "../type-expander/type-expander.lp2.rkt"
                  "../type-expander/multi-id.lp2.rkt"
                  "meta-struct.rkt")
         
         ;(begin-for-syntax
         ;<multiassoc-syntax>)
         
         (provide define-graph)
         <first-step>
         <second-step>)]

In @tc[module-test], we have to require @tc[type-expander] because it provides a
@tc[:] macro which is a different identifier than the one from typed/racket,
therefore the @tc[:] bound in the @tc[graph] macro with @tc[:colon] would
not match the one from @tc[typed/racket]

@chunk[<module-test>
       (module* test typed/racket
         (require (submod "..")
                  (only-in "../lib/low.rkt" cars cdrs check-equal?:)
                  (only-in "structure.lp2.rkt" structure-get)
                  "../type-expander/type-expander.lp2.rkt"
                  typed/rackunit)
         
         (provide g)
         <use-example>
         <type-example>)]

The whole file, finally:

@chunk[<*>
       (begin
         <module-main>
         
         (require 'main)
         (provide (all-from-out 'main))
         
         <module-test>)]